@ossy/media-tasks 3.18.0 → 3.19.0

package/src/text-to-voice.js

@@ -0,0 +1,160 @@
+/**
+ * Text-to-voice via OpenRouter TTS (#898).
+ *
+ * Provider: shared `openrouter` integration (`OPENROUTER_API_KEY`) — OpenRouter
+ * exposes OpenAI-compatible `/audio/speech` (see
+ * https://openrouter.ai/docs/guides/overview/multimodal/tts). Default model is
+ * `mistralai/voxtral-mini-tts-2603` (listed in OpenRouter speech catalog).
+ * Output is MP3 (`audio/mpeg`).
+ */
+
+import { MARKDOWN_DOCUMENT_TYPE } from './run-prompt.js'
+
+/** @see https://openrouter.ai/docs/guides/overview/multimodal/tts */
+export const DEFAULT_TEXT_TO_VOICE_MODEL = 'mistralai/voxtral-mini-tts-2603'
+export const DEFAULT_TEXT_TO_VOICE_VOICE = 'en_paul_neutral'
+export const DEFAULT_TEXT_TO_VOICE_FORMAT = 'mp3'
+export const TEXT_TO_VOICE_CONTENT_TYPE = 'audio/mpeg'
+
+/** Soft character ceiling for spoken input. */
+export const MAX_TEXT_TO_VOICE_CHARS = 4096
+
+/** Legacy direct-OpenAI short model names → OpenRouter default. */
+const LEGACY_MODEL_ALIASES = Object.freeze({
+  'tts-1': DEFAULT_TEXT_TO_VOICE_MODEL,
+  'tts-1-hd': DEFAULT_TEXT_TO_VOICE_MODEL,
+})
+
+/** Legacy OpenAI voice names → Voxtral defaults (provider voices differ). */
+const LEGACY_VOICE_ALIASES = Object.freeze({
+  alloy: 'en_paul_neutral',
+  echo: 'en_paul_neutral',
+  fable: 'en_paul_cheerful',
+  onyx: 'en_paul_confident',
+  nova: 'en_paul_happy',
+  shimmer: 'en_paul_excited',
+})
+
+/**
+ * Voices are provider-specific — accept any non-empty id; map legacy OpenAI names.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function normalizeVoice (value) {
+  const raw = typeof value === 'string' ? value.trim() : ''
+  if (!raw) return DEFAULT_TEXT_TO_VOICE_VOICE
+  const lower = raw.toLowerCase()
+  if (LEGACY_VOICE_ALIASES[lower]) return LEGACY_VOICE_ALIASES[lower]
+  return raw
+}
+
+/**
+ * Accept OpenRouter model slugs; map legacy `tts-1` / `tts-1-hd` aliases.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function normalizeModel (value) {
+  const raw = typeof value === 'string' ? value.trim() : ''
+  if (!raw) return DEFAULT_TEXT_TO_VOICE_MODEL
+  const lower = raw.toLowerCase()
+  if (LEGACY_MODEL_ALIASES[lower]) return LEGACY_MODEL_ALIASES[lower]
+  // OpenRouter slugs are provider/model (e.g. mistralai/voxtral-mini-tts-2603).
+  if (raw.includes('/')) return raw
+  return DEFAULT_TEXT_TO_VOICE_MODEL
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function normalizeSpeechText (value) {
+  if (typeof value !== 'string') return ''
+  return value.trim()
+}
+
+/**
+ * Truncate to the TTS character ceiling.
+ *
+ * @param {string} text
+ * @returns {{ text: string, truncated: boolean }}
+ */
+export function clampSpeechText (text) {
+  const normalized = normalizeSpeechText(text)
+  if (normalized.length <= MAX_TEXT_TO_VOICE_CHARS) {
+    return { text: normalized, truncated: false }
+  }
+  return {
+    text: normalized.slice(0, MAX_TEXT_TO_VOICE_CHARS),
+    truncated: true,
+  }
+}
+
+/**
+ * Prefer explicit input text; otherwise use Markdown `content.body` or file bytes.
+ *
+ * @param {{
+ *   inputText?: unknown,
+ *   resource?: object | null,
+ *   fileText?: string | null,
+ * }} opts
+ * @returns {string}
+ */
+export function resolveSpeechSourceText ({ inputText, resource, fileText } = {}) {
+  const fromInput = normalizeSpeechText(inputText)
+  if (fromInput) return fromInput
+
+  if (resource?.type === MARKDOWN_DOCUMENT_TYPE) {
+    const body = resource?.content?.body
+    if (typeof body === 'string' && body.trim()) return body.trim()
+  }
+
+  if (typeof fileText === 'string' && fileText.trim()) return fileText.trim()
+  return ''
+}
+
+/**
+ * Call OpenRouter TTS (OpenAI-compatible audio.speech) and return MP3 bytes.
+ *
+ * @param {{ audio: { speech: { create: Function } } }} client
+ * @param {{ text: string, voice?: string, model?: string }} opts
+ * @returns {Promise<{
+ *   buffer: Buffer,
+ *   voice: string,
+ *   model: string,
+ *   format: string,
+ *   contentType: string,
+ *   size: number,
+ *   truncated: boolean,
+ *   characterCount: number,
+ * }>}
+ */
+export async function synthesizeSpeech (client, opts = {}) {
+  const voice = normalizeVoice(opts.voice)
+  const model = normalizeModel(opts.model)
+  const { text, truncated } = clampSpeechText(opts.text)
+  if (!text) {
+    throw new Error('[media-tasks/text-to-voice] text is required')
+  }
+
+  const response = await client.audio.speech.create({
+    model,
+    voice,
+    input: text,
+    response_format: DEFAULT_TEXT_TO_VOICE_FORMAT,
+  })
+
+  const arrayBuffer = await response.arrayBuffer()
+  const buffer = Buffer.from(arrayBuffer)
+  return {
+    buffer,
+    voice,
+    model,
+    format: DEFAULT_TEXT_TO_VOICE_FORMAT,
+    contentType: TEXT_TO_VOICE_CONTENT_TYPE,
+    size: buffer.length,
+    truncated,
+    characterCount: text.length,
+  }
+}

package/src/text-to-voice.schema.js

@@ -0,0 +1,51 @@
+import { TASK_OUTPUT_PROVENANCE_FIELDS } from '@ossy/schema'
+
+export default {
+  name: 'Text to voice',
+  id: '@ossy/media-tasks/schema/text-to-voice',
+  categoryName: 'Media processing',
+  icon: 'mic',
+  fields: [
+    {
+      name: 'voice',
+      type: 'text',
+      description: 'TTS voice id (provider-dependent)',
+    },
+    {
+      name: 'model',
+      type: 'text',
+      description: 'OpenRouter TTS model slug',
+    },
+    {
+      name: 'format',
+      type: 'text',
+      description: 'Audio container format (mp3)',
+    },
+    {
+      name: 'contentType',
+      type: 'text',
+      description: 'MIME type of the audio bytes',
+    },
+    {
+      name: 'size',
+      type: 'number',
+      description: 'Audio byte length',
+    },
+    {
+      name: 'characterCount',
+      type: 'number',
+      description: 'Characters sent to TTS (after clamp)',
+    },
+    {
+      name: 'truncated',
+      type: 'boolean',
+      description: 'True when input was truncated to the TTS character limit',
+    },
+    {
+      name: 'audioKey',
+      type: 'text',
+      description: 'Storage key for the MP3 binary artifact',
+    },
+    ...TASK_OUTPUT_PROVENANCE_FIELDS,
+  ],
+}

package/src/text-to-voice.spec.js

@@ -0,0 +1,102 @@
+import {
+  DEFAULT_TEXT_TO_VOICE_MODEL,
+  DEFAULT_TEXT_TO_VOICE_VOICE,
+  MAX_TEXT_TO_VOICE_CHARS,
+  TEXT_TO_VOICE_CONTENT_TYPE,
+  clampSpeechText,
+  normalizeModel,
+  normalizeVoice,
+  resolveSpeechSourceText,
+  synthesizeSpeech,
+} from './text-to-voice.js'
+import { MARKDOWN_DOCUMENT_TYPE } from './run-prompt.js'
+
+describe('text-to-voice helpers', () => {
+  it('normalizes voice and OpenRouter model slugs', () => {
+    expect(normalizeVoice('en_paul_happy')).toBe('en_paul_happy')
+    expect(normalizeVoice('NOVA')).toBe('en_paul_happy')
+    expect(normalizeVoice('')).toBe(DEFAULT_TEXT_TO_VOICE_VOICE)
+    expect(normalizeModel('mistralai/voxtral-mini-tts-2603')).toBe('mistralai/voxtral-mini-tts-2603')
+    expect(normalizeModel('google/gemini-3.8-flash-lite-tts')).toBe('google/gemini-3.8-flash-lite-tts')
+    expect(normalizeModel('TTS-1-HD')).toBe(DEFAULT_TEXT_TO_VOICE_MODEL)
+    expect(normalizeModel('tts-1')).toBe(DEFAULT_TEXT_TO_VOICE_MODEL)
+    expect(normalizeModel('openai/gpt-4o-mini-tts-2025-12-15')).toBe('openai/gpt-4o-mini-tts-2025-12-15')
+    expect(normalizeModel('whisper')).toBe(DEFAULT_TEXT_TO_VOICE_MODEL)
+  })
+
+  it('clamps speech text to the character ceiling', () => {
+    const long = 'a'.repeat(MAX_TEXT_TO_VOICE_CHARS + 10)
+    const clamped = clampSpeechText(long)
+    expect(clamped.truncated).toBe(true)
+    expect(clamped.text).toHaveLength(MAX_TEXT_TO_VOICE_CHARS)
+
+    expect(clampSpeechText('  hello  ')).toEqual({ text: 'hello', truncated: false })
+  })
+
+  it('resolves speech source from input, markdown, or file text', () => {
+    expect(resolveSpeechSourceText({ inputText: ' from input ' })).toBe('from input')
+    expect(resolveSpeechSourceText({
+      resource: { type: MARKDOWN_DOCUMENT_TYPE, content: { body: ' md body ' } },
+    })).toBe('md body')
+    expect(resolveSpeechSourceText({ fileText: ' file bytes ' })).toBe('file bytes')
+    expect(resolveSpeechSourceText({})).toBe('')
+  })
+})
+
+describe('synthesizeSpeech', () => {
+  it('calls OpenRouter-compatible audio.speech and returns an MP3 buffer', async () => {
+    const fakeMp3 = Buffer.from([0xff, 0xfb, 0x90, 0x00])
+    const calls = []
+    const client = {
+      audio: {
+        speech: {
+          create: async (args) => {
+            calls.push(args)
+            return {
+              arrayBuffer: async () => fakeMp3.buffer.slice(
+                fakeMp3.byteOffset,
+                fakeMp3.byteOffset + fakeMp3.byteLength,
+              ),
+            }
+          },
+        },
+      },
+    }
+
+    const result = await synthesizeSpeech(client, {
+      text: 'Hello Ossy',
+      voice: 'en_paul_happy',
+      model: 'mistralai/voxtral-mini-tts-2603',
+    })
+
+    expect(calls[0]).toEqual({
+      model: 'mistralai/voxtral-mini-tts-2603',
+      voice: 'en_paul_happy',
+      input: 'Hello Ossy',
+      response_format: 'mp3',
+    })
+    expect(result.contentType).toBe(TEXT_TO_VOICE_CONTENT_TYPE)
+    expect(result.format).toBe('mp3')
+    expect(result.voice).toBe('en_paul_happy')
+    expect(result.model).toBe('mistralai/voxtral-mini-tts-2603')
+    expect(result.characterCount).toBe(10)
+    expect(result.truncated).toBe(false)
+    expect(Buffer.compare(result.buffer, fakeMp3)).toBe(0)
+  })
+
+  it('rejects empty text', async () => {
+    let called = false
+    const client = {
+      audio: {
+        speech: {
+          create: async () => {
+            called = true
+            return { arrayBuffer: async () => new ArrayBuffer(0) }
+          },
+        },
+      },
+    }
+    await expect(synthesizeSpeech(client, { text: '   ' })).rejects.toThrow(/text is required/)
+    expect(called).toBe(false)
+  })
+})

package/src/text-to-voice.task.js

@@ -0,0 +1,191 @@
+import { createLogger } from '@ossy/observability'
+import { StorageClient } from '@ossy/platform'
+import { originalObjectKey, taskArtifactObjectKey } from '@ossy/platform/storage-keys'
+import { GetResource, placeTaskArtifacts } from '@ossy/resources'
+import { loadSourceBuffer } from './load-source-buffer.js'
+import { resolveConfiguredPlacements } from './resolve-configured-placement.js'
+import {
+  MARKDOWN_DOCUMENT_TYPE,
+  isTextContentType,
+  markdownDocumentBody,
+} from './run-prompt.js'
+import {
+  DEFAULT_TEXT_TO_VOICE_MODEL,
+  DEFAULT_TEXT_TO_VOICE_VOICE,
+  resolveSpeechSourceText,
+  synthesizeSpeech,
+} from './text-to-voice.js'
+
+const log = createLogger('media-tasks')
+
+const TASK_ID = '@ossy/media-tasks/tasks/text-to-voice'
+const SCHEMA_ID = '@ossy/media-tasks/schema/text-to-voice'
+const CONCEPT = 'text-to-voice'
+const AUDIO_ARTIFACT = 'audio'
+const OUTPUT = {
+  name: 'speech',
+  kind: 'location',
+  schemaId: SCHEMA_ID,
+  contentType: 'application/json',
+}
+
+export const metadata = {
+  id: TASK_ID,
+  triggers: [
+    {
+      kind: 'on_action',
+      action: '@ossy/media-tasks/actions/text-to-voice',
+    },
+    {
+      type: MARKDOWN_DOCUMENT_TYPE,
+      event: 'Created',
+    },
+    {
+      type: '@ossy/platform/schema/file',
+      event: 'Created',
+      match: { 'content.ContentType': 'text/*' },
+    },
+  ],
+  outputs: [OUTPUT],
+  inputs: [
+    {
+      name: 'text',
+      type: 'text',
+      multiline: true,
+      sources: ['payload', 'config'],
+      description: 'Text to speak. When empty, uses the Markdown body or text file contents.',
+    },
+    {
+      name: 'voice',
+      type: 'text',
+      default: DEFAULT_TEXT_TO_VOICE_VOICE,
+      sources: ['payload', 'config'],
+      description: 'OpenRouter TTS voice id (provider-specific; default en_paul_neutral for Voxtral)',
+    },
+    {
+      name: 'model',
+      type: 'text',
+      default: DEFAULT_TEXT_TO_VOICE_MODEL,
+      sources: ['payload', 'config'],
+      description: 'OpenRouter speech model slug (default mistralai/voxtral-mini-tts-2603)',
+    },
+  ],
+  configurable: true,
+}
+
+export async function run ({ event, payload, sdk, integrations, inputs }) {
+  const openrouter = integrations?.get?.('openrouter')
+  if (!openrouter) {
+    log.warn('[media-tasks/tasks/text-to-voice] openrouter integration not connected')
+    throw Object.assign(new Error('OpenRouter integration not available'), { status: 503 })
+  }
+
+  const resourceId = event?.resourceId || payload?.resourceId || null
+  log.info(`[media-tasks/tasks/text-to-voice] starting${resourceId ? ` for resource ${resourceId}` : ''}`)
+
+  let resource = null
+  let fileText = null
+  if (resourceId) {
+    resource = await sdk.invoke(GetResource, { resourceId })
+    fileText = await loadFileText(resource)
+  }
+
+  const sourceText = resolveSpeechSourceText({
+    inputText: inputs?.text,
+    resource,
+    fileText,
+  })
+  if (!sourceText) {
+    throw Object.assign(
+      new Error('[media-tasks/tasks/text-to-voice] text is required (input, Markdown body, or text file)'),
+      { status: 400 },
+    )
+  }
+
+  const speech = await synthesizeSpeech(openrouter, {
+    text: sourceText,
+    voice: inputs?.voice,
+    model: inputs?.model,
+  })
+
+  if (!resource?.id) {
+    return {
+      output: OUTPUT.name,
+      voice: speech.voice,
+      model: speech.model,
+      format: speech.format,
+      contentType: speech.contentType,
+      size: speech.size,
+      characterCount: speech.characterCount,
+      truncated: speech.truncated,
+      placedResourceIds: [],
+    }
+  }
+
+  const audioKey = taskArtifactObjectKey(resource.id, CONCEPT, AUDIO_ARTIFACT)
+  await StorageClient.save(audioKey, speech.buffer)
+  log.info(`[media-tasks/tasks/text-to-voice] saved audio ${audioKey} (${speech.size} bytes)`)
+
+  const body = {
+    voice: speech.voice,
+    model: speech.model,
+    format: speech.format,
+    contentType: speech.contentType,
+    size: speech.size,
+    characterCount: speech.characterCount,
+    truncated: speech.truncated,
+    audioKey,
+  }
+
+  const metaKey = taskArtifactObjectKey(resource.id, CONCEPT, OUTPUT.name)
+  await StorageClient.save(metaKey, Buffer.from(JSON.stringify(body), 'utf8'))
+  log.info(`[media-tasks/tasks/text-to-voice] saved ${metaKey}`)
+
+  const placementLocations = await resolveConfiguredPlacements(sdk, TASK_ID, OUTPUT.name)
+  const placed = await placeTaskArtifacts({
+    sdk,
+    sourceResource: resource,
+    taskId: TASK_ID,
+    output: OUTPUT,
+    body,
+    artifactKey: metaKey,
+    placementLocations,
+  })
+  if (placed.length) {
+    log.info(`[media-tasks/tasks/text-to-voice] placed ${placed.length} resource(s)`)
+  } else {
+    log.info('[media-tasks/tasks/text-to-voice] artifact only (no placement location configured)')
+  }
+
+  return {
+    output: OUTPUT.name,
+    key: metaKey,
+    audioKey,
+    voice: speech.voice,
+    model: speech.model,
+    format: speech.format,
+    contentType: speech.contentType,
+    size: speech.size,
+    characterCount: speech.characterCount,
+    truncated: speech.truncated,
+    placedResourceIds: placed.map((r) => r.id),
+    placedResourceId: placed[0]?.id ?? null,
+  }
+}
+
+/**
+ * @param {object | null | undefined} resource
+ * @returns {Promise<string | null>}
+ */
+async function loadFileText (resource) {
+  if (!resource) return null
+  if (resource.type === MARKDOWN_DOCUMENT_TYPE) {
+    return markdownDocumentBody(resource) || null
+  }
+  const contentType = resource?.content?.ContentType || ''
+  if (!isTextContentType(contentType)) return null
+  // content.Key is stripped by the API media layer; derive from resource id.
+  const key = originalObjectKey(resource.id)
+  const buffer = await loadSourceBuffer(key)
+  return buffer ? buffer.toString('utf8') : null
+}

package/src/visual-content-descriptors.action.js

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

package/src/visual-content-descriptors.task.js

@@ -36,6 +36,10 @@ export const metadata = {
       event: 'Created',
       match: { 'content.ContentType': 'video/*' },
     },
+    {
+      kind: 'on_action',
+      action: '@ossy/media-tasks/actions/visual-content-descriptors',
+    },
   ],
   outputs: [OUTPUT],
   inputs: [
@@ -51,7 +55,10 @@ export const metadata = {
 }
 
 export async function run ({ event, payload, req, sdk, integrations, inputs }) {
-  const resourceId = event.resourceId
+  const resourceId = event?.resourceId || payload?.resourceId
+  if (!resourceId) {
+    throw new Error('[media-tasks/tasks/visual-content-descriptors] resourceId is required')
+  }
 
   log.info(`[media-tasks/tasks/visual-content-descriptors] starting for resource ${resourceId}`)