@ossy/media-tasks 3.18.0 → 3.19.0

package/README.md

@@ -10,10 +10,13 @@ Tasks in this package are registered with `TaskService.RegisterTask()` at API st
 |---------|------------------------------|-------------|
 | `@ossy/media-tasks/tasks/resize-common-web` | file `Created` + `image/*` | Common web sizes + BlurHash → storage keys under the source id |
 | `@ossy/media-tasks/tasks/extract-colors` | file `Created` + `image/*` | Dominant color + palette JSON → storage |
+| `@ossy/media-tasks/tasks/convert-common-image` | file `Created` + `image/*` (+ primary action) | First-slice format convert via **sharp**: auto-run for HEIC/HEIF/TIFF/BMP/AVIF **and** jpeg/png/webp → configurable `jpeg`/`png`/`webp` (default jpeg; skips when already the target). Manual Storage → Tasks invoke accepts any image. Inputs `format`, `quality`. |
 | `@ossy/media-tasks/tasks/visual-content-descriptors` | file `Created` + `image/*` / `video/*` | OpenRouter vision → title/description/tags/alt JSON → storage. Input `model` (config or payload); default `openai/gpt-4o-mini`, overridable per trigger. |
 | `@ossy/media-tasks/tasks/run-prompt` | file `Created` + `text/*` / `image/*` / `application/json`, or `@ossy/resources/schema/markdown` `Created` | OpenRouter chat completion. Inputs `prompt` (required), `model` (default `openai/gpt-4o-mini`), optional `temperature`. File bytes or the Markdown document `body` are the context. |
+| `@ossy/media-tasks/tasks/convert-common-audio` | file `Created` + `audio/*`, or `on_action` | General audio format converter via ffmpeg: MP3 (default), AAC, OGG, WAV, AIFF, FLAC. Inputs `format`, `quality`. Skips uploads already in the target container MIME. |
+| `@ossy/media-tasks/tasks/text-to-voice` | `on_action` + Markdown `Created` + file `Created` + `text/*` | OpenRouter TTS → MP3. Inputs `text` (optional when a resource supplies body/bytes), `voice` (default `en_paul_neutral`), `model` (OpenRouter slug; default `mistralai/voxtral-mini-tts-2603`). |
 
-All four set **`configurable: true`**. Workspaces arm them on `/automation` with their own `triggers[]` (within the ceiling above) and optional placement folders. Until armed, they do not run.
+All seven set **`configurable: true`**. Workspaces arm them on `/automation` with their own `triggers[]` (within the ceiling above) and optional placement folders. Until armed, they do not run.
 
 ## Task outputs
 
@@ -24,8 +27,11 @@ All four set **`configurable: true`**. Workspaces arm them on `/automation` with
 |------|--------|---------------|
 | extract-colors | `palette` | `@ossy/media-tasks/schema/extract-colors` |
 | resize-common-web | `sizes` (+ binary keys) | `@ossy/media-tasks/schema/resize-common-web` (JSON meta placed; binaries via URL) |
+| convert-common-image | `converted` (+ `image` binary) | `@ossy/media-tasks/schema/convert-common-image` (JSON meta placed; bytes at `…-image`) |
 | visual-content-descriptors | `descriptors` | `@ossy/media-tasks/schema/visual-content-descriptors` |
 | run-prompt | `completion` | `@ossy/platform/schema/text-completion` (freeform text/md — a platform schema, not feature-owned) |
+| convert-common-audio | `converted` (+ `audio` binary) | `@ossy/media-tasks/schema/convert-common-audio` (JSON meta placed; bytes at `…-audio`) |
+| text-to-voice | `speech` (+ `audio` MP3) | `@ossy/media-tasks/schema/text-to-voice` (JSON meta placed; bytes at `…-audio`) |
 
 See [TaskOutput.md](../../docs/concepts/TaskOutput.md).
 
@@ -55,12 +61,16 @@ export async function run ({ event, sdk, inputs }) { ... }
 
 | Id | Credentials | Used by |
 |----|-------------|---------|
-| `openrouter` | `OPENROUTER_API_KEY` (required); optional `OPENROUTER_SITE_URL`, `OPENROUTER_APP_TITLE`, `OPENROUTER_BASE_URL` | `visual-content-descriptors` and `run-prompt` via `integrations.get('openrouter')` |
+| `openrouter` | `OPENROUTER_API_KEY` (required); optional `OPENROUTER_SITE_URL`, `OPENROUTER_APP_TITLE`, `OPENROUTER_BASE_URL` | `visual-content-descriptors`, `run-prompt`, and `text-to-voice` via `integrations.get('openrouter')` |
 
 OpenRouter is OpenAI-compatible (`baseURL` `https://openrouter.ai/api/v1`). The VCD `model` input defaults to `openai/gpt-4o-mini`. A workspace can set another slug as the instance default, and a different slug on a single trigger (folder or MIME). An invoke payload still wins.
 
 `run-prompt` sends the resolved prompt as the user message. A matching file is appended as context (text/JSON excerpt, or an image data URL). A Markdown document (`@ossy/resources/schema/markdown`) sends `content.body` instead. The completion is stored at `{resourceId}:task-run-prompt-completion` and placed only when the workspace set a folder. **Run now** invokes `@ossy/media-tasks/actions/run-prompt` with the editor values; without a resource id the completion is returned on the task run and not stored.
 
+**Provider decision (#898):** TTS uses the shared `openrouter` integration (OpenRouter `/audio/speech`, OpenAI-compatible). Default model `mistralai/voxtral-mini-tts-2603` (in OpenRouter's speech catalog); legacy `tts-1` / `tts-1-hd` aliases map onto that slug. Writes an MP3 artifact. Character usage is **not** counted against the ADR 0017 LLM token cap.
+
+`text-to-voice` resolves spoken text from (1) the `text` input, else (2) Markdown `content.body`, else (3) text-file bytes. Primary action `@ossy/media-tasks/actions/text-to-voice` supports manual Storage → Tasks invokes (epic #889 / #934).
+
 ## Usage metering and a monthly token cap (ADR 0017)
 
 Both OpenRouter tasks read `response.usage` and return it as `result.usage = { model, promptTokens, completionTokens, totalTokens }`. `TaskRunService` forwards this onto `MeteringService.record()` automatically (any task returning `result.usage` in this shape gets metered — no per-task wiring needed).
@@ -71,5 +81,21 @@ Before calling OpenRouter, each task calls `assertLlmUsageBudget()` (`@ossy/plat
 
 - **`sharp`** (peer) — image resizing + metadata
 - **`blurhash`** — encode compact placeholders after resize
-- **`openai`** (peer) — OpenAI SDK client pointed at OpenRouter
+- **`openai`** (peer) — OpenAI SDK client pointed at OpenRouter (chat + TTS)
+- **`ffmpeg-static`** (optional peer; also a media-tasks **devDependency** so CI/unit tests resolve a binary) — portable ffmpeg for `convert-common-audio`; otherwise `FFMPEG_PATH` or system `ffmpeg` on PATH
 - **`@ossy/platform`** — `StorageClient` for reading/writing file bytes
+
+## Audio output formats (`convert-common-audio`)
+
+`convert-common-audio` converts between these container formats via ffmpeg. Inputs: `format` (default `mp3`) and `quality` 1–100 for lossy codecs (ignored for wav/aiff/flac). Auto-run on `audio/*` Created skips uploads already in the target container MIME; Storage → Tasks (`on_action`) always offers the format/quality dialog.
+
+| Format | Codec | Content-Type | Quality mapping (input 1–100) |
+|--------|-------|--------------|-------------------------------|
+| `mp3` (default) | `libmp3lame` | `audio/mpeg` | VBR `q:a` 0–9 — `Math.round((1 - quality/100) * 9)` (100 → 0 best) |
+| `aac` | `aac` | `audio/aac` | Bitrate 64k–320k — `64 + (quality/100) * 256` |
+| `ogg` | `libvorbis` | `audio/ogg` | VBR `q:a` 1–10 — `max(1, round(quality/10))` |
+| `wav` | `pcm_s16le` | `audio/wav` | Lossless PCM — quality ignored |
+| `aiff` | `pcm_s16be` | `audio/aiff` | Lossless PCM — quality ignored |
+| `flac` | `flac` | `audio/flac` | Lossless — fixed `compression_level` 5 |
+
+JSON meta artifact `converted` stores `format`, `contentType`, `sourceContentType`, `quality`, `size`, `audioKey`; binary bytes live at `…-audio`. Storage → Tasks shows an inline player plus `FORMAT · quality N`. Binary Content-Type uses magic-byte sniffing (WAV/AIFF/OGG/FLAC/MP3/AAC). DJ-specific preprocessing (BPM/key, Camelot tags, EBU R128 for rekordbox/CDJ USB) is tracked separately in [#951](https://github.com/ossy-se/ossy/issues/951) (`analyze-dj-audio`, not shipped yet).

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@ossy/media-tasks",
-  "version": "3.18.0",
-  "description": "Changestream-triggered media processing tasks (image resize, AI descriptors, prompts)",
+  "version": "3.19.0",
+  "description": "Changestream-triggered media processing tasks (image resize, audio convert, AI descriptors, prompts)",
   "type": "module",
   "main": "./src/index.js",
   "module": "./src/index.js",
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./embed-resource": "./src/embed-resource.js"
   },
   "ossy": {
     "src": "./src"
@@ -17,15 +18,24 @@
   },
   "dependencies": {
     "@ossy/observability": "^3.0.9",
-    "@ossy/platform": "^3.18.0",
-    "@ossy/resources": "^3.18.0",
+    "@ossy/platform": "^3.19.0",
+    "@ossy/resources": "^3.19.0",
     "@ossy/schema": "^3.18.0",
     "blurhash": "^2.0.5"
   },
   "peerDependencies": {
+    "ffmpeg-static": ">=5",
     "openai": ">=4",
     "sharp": ">=0.34"
   },
+  "peerDependenciesMeta": {
+    "ffmpeg-static": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "ffmpeg-static": "^5.3.0"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
@@ -36,5 +46,5 @@
   ],
   "author": "Ossy <yourfriends@ossy.se> (https://ossy.se)",
   "license": "MIT",
-  "gitHead": "8ceef98795a01c3b3486034db1d3b72b4350ccf1"
+  "gitHead": "0ac103001a468f56597c02cf1c6802bf7bd89b33"
 }

package/src/Definition.js

@@ -0,0 +1,7 @@
+export const Definition = {
+  id: 'media-tasks',
+  title: 'Media Tasks',
+  description: 'Automated image processing tasks — extract color palettes, generate resize variants, and run visual content analysis.',
+  icon: 'image',
+  status: ['beta'],
+}

package/src/convert-common-audio.action.js

@@ -0,0 +1,5 @@
+export const metadata = {
+  id: '@ossy/media-tasks/actions/convert-common-audio',
+  access: 'workspace',
+  label: 'automation.task.convert-common-audio.title',
+}

package/src/convert-common-audio.js

@@ -0,0 +1,243 @@
+/**
+ * General audio format converter (#897 — generalised from DJ-specific).
+ *
+ * Converts between common audio formats via ffmpeg. DJ/PCM preprocessing
+ * (BPM, Camelot key, rekordbox/CDJ USB prep) is tracked separately in #951
+ * (`analyze-dj-audio`) — that task is not implemented in this package yet.
+ *
+ * Supported output formats: mp3, aac, ogg, wav, aiff, flac
+ * Default: mp3
+ *
+ * Dependency: system `ffmpeg` on PATH, or optional peer `ffmpeg-static`
+ * (or `FFMPEG_PATH`). No fluent-ffmpeg wrapper — spawn is enough.
+ */
+
+import { spawn } from 'node:child_process'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+/** @type {ReadonlyArray<string>} */
+export const COMMON_AUDIO_TARGET_FORMATS = Object.freeze([
+  'mp3', 'aac', 'ogg', 'wav', 'aiff', 'flac',
+])
+
+/** @type {Readonly<Record<string, string>>} */
+export const COMMON_AUDIO_FORMAT_CONTENT_TYPES = Object.freeze({
+  mp3: 'audio/mpeg',
+  aac: 'audio/aac',
+  ogg: 'audio/ogg',
+  wav: 'audio/wav',
+  aiff: 'audio/aiff',
+  flac: 'audio/flac',
+})
+
+/** MIME types already matching a target container (upload auto-run skip). */
+export const COMMON_AUDIO_TARGET_MIME_TYPES = Object.freeze({
+  mp3: Object.freeze(['audio/mpeg', 'audio/mp3']),
+  aac: Object.freeze(['audio/aac', 'audio/x-aac']),
+  ogg: Object.freeze(['audio/ogg']),
+  wav: Object.freeze(['audio/wav', 'audio/x-wav', 'audio/wave']),
+  aiff: Object.freeze(['audio/aiff', 'audio/x-aiff']),
+  flac: Object.freeze(['audio/flac', 'audio/x-flac']),
+})
+
+/** ffmpeg codec per output format. */
+const FORMAT_CODEC = Object.freeze({
+  mp3: 'libmp3lame',
+  aac: 'aac',
+  ogg: 'libvorbis',
+  wav: 'pcm_s16le',
+  aiff: 'pcm_s16be',
+  flac: 'flac',
+})
+
+export const DEFAULT_COMMON_AUDIO_FORMAT = 'mp3'
+export const DEFAULT_COMMON_AUDIO_QUALITY = 85
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function normalizeCommonAudioFormat (value) {
+  const raw = typeof value === 'string' ? value.trim().toLowerCase() : ''
+  if (raw === 'aif') return 'aiff'
+  if (raw === 'm4a' || raw === 'mp4') return 'aac'
+  if (COMMON_AUDIO_TARGET_FORMATS.includes(raw)) return raw
+  return DEFAULT_COMMON_AUDIO_FORMAT
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number}
+ */
+export function normalizeCommonAudioQuality (value) {
+  const n = typeof value === 'number' ? value : Number(String(value ?? '').trim())
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_COMMON_AUDIO_QUALITY
+  return Math.max(1, Math.min(100, Math.round(n)))
+}
+
+/**
+ * @param {unknown} contentType
+ * @returns {string}
+ */
+export function normalizeContentType (contentType) {
+  return String(contentType || '').split(';')[0].trim().toLowerCase()
+}
+
+/**
+ * @param {unknown} contentType
+ * @returns {boolean}
+ */
+export function isAudioContentType (contentType) {
+  return normalizeContentType(contentType).startsWith('audio/')
+}
+
+/**
+ * @param {string} format
+ * @returns {string}
+ */
+export function contentTypeForCommonAudioFormat (format) {
+  const normalized = normalizeCommonAudioFormat(format)
+  return COMMON_AUDIO_FORMAT_CONTENT_TYPES[normalized] || COMMON_AUDIO_FORMAT_CONTENT_TYPES.mp3
+}
+
+/**
+ * Skip when the source MIME already matches the requested target container.
+ *
+ * @param {unknown} sourceContentType
+ * @param {string} targetFormat
+ * @returns {boolean}
+ */
+export function isAlreadyCommonAudioTargetFormat (sourceContentType, targetFormat) {
+  const format = normalizeCommonAudioFormat(targetFormat)
+  const mime = normalizeContentType(sourceContentType)
+  const accepted = COMMON_AUDIO_TARGET_MIME_TYPES[format] || []
+  return accepted.includes(mime)
+}
+
+/**
+ * Build ffmpeg quality flags for a given format and quality (1–100).
+ *
+ * @param {string} format
+ * @param {number} quality  1–100
+ * @returns {string[]}
+ */
+export function qualityFlagsForFormat (format, quality) {
+  switch (format) {
+    case 'mp3': {
+      // VBR: q:a 0 (best) – 9 (worst). quality 100→0, quality 1→9.
+      const q = Math.round((1 - quality / 100) * 9)
+      return ['-q:a', String(q)]
+    }
+    case 'ogg': {
+      // q:a 0 (worst) – 10 (best). quality 100→10, quality 1→1.
+      const q = Math.max(1, Math.round(quality / 10))
+      return ['-q:a', String(q)]
+    }
+    case 'aac': {
+      // Map quality 1–100 → 64k–320k.
+      const kbps = Math.round(64 + (quality / 100) * 256)
+      return ['-b:a', `${kbps}k`]
+    }
+    case 'flac':
+      // compression_level 0 (fastest) – 12 (smallest). Default 5 is fine.
+      return ['-compression_level', '5']
+    default:
+      // wav / aiff — PCM, lossless, no quality flags needed.
+      return []
+  }
+}
+
+/**
+ * Resolve the ffmpeg binary: `FFMPEG_PATH`, optional `ffmpeg-static`, then PATH.
+ *
+ * @returns {Promise<string>}
+ */
+export async function resolveFfmpegPath () {
+  if (typeof process.env.FFMPEG_PATH === 'string' && process.env.FFMPEG_PATH.trim()) {
+    return process.env.FFMPEG_PATH.trim()
+  }
+  try {
+    const mod = await import('ffmpeg-static')
+    const path = mod?.default || mod
+    if (typeof path === 'string' && path) return path
+  } catch {
+    // peer optional — fall through to system binary
+  }
+  return 'ffmpeg'
+}
+
+/**
+ * @param {string} ffmpegPath
+ * @param {string[]} args
+ * @returns {Promise<void>}
+ */
+export function runFfmpeg (ffmpegPath, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(ffmpegPath, args, { stdio: ['ignore', 'ignore', 'pipe'] })
+    let stderr = ''
+    child.stderr?.on('data', (chunk) => { stderr += String(chunk) })
+    child.on('error', (err) => {
+      reject(new Error(`[convert-common-audio] failed to spawn ffmpeg: ${err.message}`))
+    })
+    child.on('close', (code) => {
+      if (code === 0) { resolve(); return }
+      const detail = stderr.trim() || `exit ${code}`
+      reject(new Error(`[convert-common-audio] ffmpeg failed: ${detail}`))
+    })
+  })
+}
+
+/**
+ * Convert an audio buffer to the target format via ffmpeg.
+ *
+ * @param {Buffer} sourceBuffer
+ * @param {{ format?: string, quality?: number, ffmpegPath?: string }} [options]
+ * @returns {Promise<{
+ *   buffer: Buffer,
+ *   format: string,
+ *   contentType: string,
+ *   size: number,
+ * }>}
+ */
+export async function convertCommonAudioBuffer (sourceBuffer, options = {}) {
+  if (!Buffer.isBuffer(sourceBuffer) || sourceBuffer.length === 0) {
+    throw new Error('[convert-common-audio] source buffer is required')
+  }
+
+  const format = normalizeCommonAudioFormat(options.format)
+  const quality = normalizeCommonAudioQuality(options.quality ?? DEFAULT_COMMON_AUDIO_QUALITY)
+  const ffmpegPath = options.ffmpegPath || await resolveFfmpegPath()
+  const codec = FORMAT_CODEC[format]
+
+  const dir = await mkdtemp(join(tmpdir(), 'ossy-common-audio-'))
+  const inputPath = join(dir, 'input.bin')
+  const outputPath = join(dir, `output.${format}`)
+
+  try {
+    await writeFile(inputPath, sourceBuffer)
+    await runFfmpeg(ffmpegPath, [
+      '-y',
+      '-hide_banner',
+      '-loglevel', 'error',
+      '-i', inputPath,
+      '-vn',
+      '-acodec', codec,
+      ...qualityFlagsForFormat(format, quality),
+      outputPath,
+    ])
+    const buffer = await readFile(outputPath)
+    if (!buffer.length) {
+      throw new Error('[convert-common-audio] ffmpeg produced an empty output')
+    }
+    return {
+      buffer,
+      format,
+      contentType: contentTypeForCommonAudioFormat(format),
+      size: buffer.length,
+    }
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+}

package/src/convert-common-audio.schema.js

@@ -0,0 +1,41 @@
+import { TASK_OUTPUT_PROVENANCE_FIELDS } from '@ossy/schema'
+
+export default {
+  name: 'Convert audio format',
+  id: '@ossy/media-tasks/schema/convert-common-audio',
+  categoryName: 'Media processing',
+  icon: 'music',
+  fields: [
+    {
+      name: 'format',
+      type: 'text',
+      description: 'Output container (mp3, aac, ogg, wav, aiff, or flac)',
+    },
+    {
+      name: 'contentType',
+      type: 'text',
+      description: 'MIME type of the converted audio bytes',
+    },
+    {
+      name: 'sourceContentType',
+      type: 'text',
+      description: 'MIME type of the source upload',
+    },
+    {
+      name: 'quality',
+      type: 'number',
+      description: 'Encode quality 1–100 used for lossy formats',
+    },
+    {
+      name: 'size',
+      type: 'number',
+      description: 'Converted audio byte length',
+    },
+    {
+      name: 'audioKey',
+      type: 'text',
+      description: 'Storage key for the converted audio binary artifact',
+    },
+    ...TASK_OUTPUT_PROVENANCE_FIELDS,
+  ],
+}

package/src/convert-common-audio.spec.js

@@ -0,0 +1,188 @@
+import { spawn } from 'node:child_process'
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  DEFAULT_COMMON_AUDIO_FORMAT,
+  DEFAULT_COMMON_AUDIO_QUALITY,
+  contentTypeForCommonAudioFormat,
+  convertCommonAudioBuffer,
+  isAlreadyCommonAudioTargetFormat,
+  isAudioContentType,
+  normalizeCommonAudioFormat,
+  normalizeCommonAudioQuality,
+  qualityFlagsForFormat,
+  resolveFfmpegPath,
+} from './convert-common-audio.js'
+
+/**
+ * @param {string} ffmpegPath
+ * @param {string[]} args
+ * @param {string} outputPath
+ * @returns {Promise<Buffer>}
+ */
+async function encodeWithFfmpeg (ffmpegPath, args, outputPath) {
+  await new Promise((resolve, reject) => {
+    const child = spawn(ffmpegPath, args, { stdio: ['ignore', 'ignore', 'pipe'] })
+    let stderr = ''
+    child.stderr?.on('data', (chunk) => { stderr += String(chunk) })
+    child.on('error', reject)
+    child.on('close', (code) => {
+      if (code === 0) resolve()
+      else reject(new Error(stderr || `exit ${code}`))
+    })
+  })
+  return readFile(outputPath)
+}
+
+/**
+ * @returns {Promise<string|null>}
+ */
+async function resolveUsableFfmpegPath () {
+  const ffmpegPath = await resolveFfmpegPath()
+  try {
+    await new Promise((resolve, reject) => {
+      const child = spawn(ffmpegPath, ['-version'], { stdio: ['ignore', 'ignore', 'ignore'] })
+      child.on('error', reject)
+      child.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`exit ${code}`))))
+    })
+    return ffmpegPath
+  } catch {
+    return null
+  }
+}
+
+/**
+ * @param {string} ffmpegPath
+ * @returns {Promise<Buffer>}
+ */
+async function makeTestMp3 (ffmpegPath) {
+  const dir = await mkdtemp(join(tmpdir(), 'ossy-common-audio-fixture-'))
+  const outputPath = join(dir, 'tone.mp3')
+  try {
+    return await encodeWithFfmpeg(ffmpegPath, [
+      '-y', '-hide_banner', '-loglevel', 'error',
+      '-f', 'lavfi',
+      '-i', 'sine=frequency=440:duration=0.25',
+      '-ac', '1',
+      '-ar', '22050',
+      '-c:a', 'libmp3lame',
+      '-b:a', '128k',
+      outputPath,
+    ], outputPath)
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+}
+
+describe('convert-common-audio helpers', () => {
+  it('normalizes format (aliases + defaults)', () => {
+    expect(normalizeCommonAudioFormat('MP3')).toBe('mp3')
+    expect(normalizeCommonAudioFormat('aif')).toBe('aiff')
+    expect(normalizeCommonAudioFormat('m4a')).toBe('aac')
+    expect(normalizeCommonAudioFormat('mp4')).toBe('aac')
+    expect(normalizeCommonAudioFormat('nope')).toBe(DEFAULT_COMMON_AUDIO_FORMAT)
+    expect(normalizeCommonAudioFormat('')).toBe(DEFAULT_COMMON_AUDIO_FORMAT)
+  })
+
+  it('normalizes quality', () => {
+    expect(normalizeCommonAudioQuality(85)).toBe(85)
+    expect(normalizeCommonAudioQuality(0)).toBe(DEFAULT_COMMON_AUDIO_QUALITY)
+    expect(normalizeCommonAudioQuality(150)).toBe(100)
+    expect(normalizeCommonAudioQuality('bad')).toBe(DEFAULT_COMMON_AUDIO_QUALITY)
+  })
+
+  it('recognizes audio MIME and already-converted sources', () => {
+    expect(isAudioContentType('audio/mpeg')).toBe(true)
+    expect(isAudioContentType('image/png')).toBe(false)
+    expect(isAlreadyCommonAudioTargetFormat('audio/mpeg', 'mp3')).toBe(true)
+    expect(isAlreadyCommonAudioTargetFormat('audio/mp3', 'mp3')).toBe(true)
+    expect(isAlreadyCommonAudioTargetFormat('audio/wav', 'wav')).toBe(true)
+    expect(isAlreadyCommonAudioTargetFormat('audio/x-wav', 'wav')).toBe(true)
+    expect(isAlreadyCommonAudioTargetFormat('audio/aiff', 'aiff')).toBe(true)
+    expect(isAlreadyCommonAudioTargetFormat('audio/flac', 'flac')).toBe(true)
+    expect(isAlreadyCommonAudioTargetFormat('audio/mpeg', 'wav')).toBe(false)
+    expect(contentTypeForCommonAudioFormat('mp3')).toBe('audio/mpeg')
+    expect(contentTypeForCommonAudioFormat('aiff')).toBe('audio/aiff')
+    expect(contentTypeForCommonAudioFormat('flac')).toBe('audio/flac')
+  })
+
+  it('builds correct ffmpeg quality flags', () => {
+    // MP3 VBR: quality 100 → q:a 0, quality 1 → q:a 9
+    expect(qualityFlagsForFormat('mp3', 100)).toEqual(['-q:a', '0'])
+    expect(qualityFlagsForFormat('mp3', 1)).toEqual(['-q:a', '9'])
+    // (1 - 85/100) * 9 = 1.35 → rounds to 1
+    expect(qualityFlagsForFormat('mp3', 85)).toEqual(['-q:a', '1'])
+    // OGG
+    expect(qualityFlagsForFormat('ogg', 100)).toEqual(['-q:a', '10'])
+    expect(qualityFlagsForFormat('ogg', 50)).toEqual(['-q:a', '5'])
+    // AAC bitrate range
+    const aacFlags = qualityFlagsForFormat('aac', 85)
+    expect(aacFlags[0]).toBe('-b:a')
+    // lossless: no quality flags
+    expect(qualityFlagsForFormat('wav', 85)).toEqual([])
+    expect(qualityFlagsForFormat('aiff', 85)).toEqual([])
+  })
+
+  it('resolves an ffmpeg binary', async () => {
+    const path = await resolveFfmpegPath()
+    expect(typeof path).toBe('string')
+    expect(path.length).toBeGreaterThan(0)
+  })
+})
+
+describe('convertCommonAudioBuffer', () => {
+  /** @type {string|null} */
+  let ffmpegPath = null
+
+  beforeAll(async () => {
+    ffmpegPath = await resolveUsableFfmpegPath()
+  })
+
+  it('converts MP3 bytes to WAV', async () => {
+    if (!ffmpegPath) {
+      throw new Error(
+        'ffmpeg binary not found — install media-tasks devDependency ffmpeg-static, or set FFMPEG_PATH / system ffmpeg',
+      )
+    }
+    const sourceBuffer = await makeTestMp3(ffmpegPath)
+    expect(sourceBuffer.length).toBeGreaterThan(0)
+
+    const result = await convertCommonAudioBuffer(sourceBuffer, { format: 'wav', ffmpegPath })
+    expect(result.format).toBe('wav')
+    expect(result.contentType).toBe('audio/wav')
+    expect(result.size).toBeGreaterThan(0)
+    expect(result.buffer.subarray(0, 4).toString('ascii')).toBe('RIFF')
+    expect(result.buffer.subarray(8, 12).toString('ascii')).toBe('WAVE')
+  })
+
+  it('converts MP3 bytes to AIFF', async () => {
+    if (!ffmpegPath) {
+      throw new Error(
+        'ffmpeg binary not found — install media-tasks devDependency ffmpeg-static, or set FFMPEG_PATH / system ffmpeg',
+      )
+    }
+    const sourceBuffer = await makeTestMp3(ffmpegPath)
+    const result = await convertCommonAudioBuffer(sourceBuffer, { format: 'aiff', ffmpegPath })
+    expect(result.format).toBe('aiff')
+    expect(result.contentType).toBe('audio/aiff')
+    expect(result.buffer.subarray(0, 4).toString('ascii')).toBe('FORM')
+  })
+
+  it('converts MP3 bytes to MP3 (re-encode)', async () => {
+    if (!ffmpegPath) {
+      throw new Error(
+        'ffmpeg binary not found — install media-tasks devDependency ffmpeg-static, or set FFMPEG_PATH / system ffmpeg',
+      )
+    }
+    const sourceBuffer = await makeTestMp3(ffmpegPath)
+    const result = await convertCommonAudioBuffer(sourceBuffer, { format: 'mp3', ffmpegPath })
+    expect(result.format).toBe('mp3')
+    expect(result.contentType).toBe('audio/mpeg')
+    expect(result.size).toBeGreaterThan(0)
+  })
+
+  it('rejects an empty source buffer', async () => {
+    await expect(convertCommonAudioBuffer(Buffer.alloc(0))).rejects.toThrow(/source buffer/)
+  })
+})