@olo-studio/studio-mcp 1.0.0 → 1.0.1

package/src/renderer.js

@@ -5,12 +5,19 @@
 import fs from 'node:fs'
 import fsp from 'node:fs/promises'
 import http from 'node:http'
+import os from 'node:os'
 import path from 'node:path'
+import { execFile } from 'node:child_process'
 import { createRequire } from 'node:module'
+import { promisify } from 'node:util'
 import JSZip from 'jszip'
 import { compileSceneSpec, findPublicStudioDir, generateSrt, parseBatchInput } from './compiler.js'
 
+const execFileAsync = promisify(execFile)
+
 export const VALID_FORMATS = ['mp4', 'webm', 'webm_alpha', 'alpha', 'chroma']
+export const VALID_FPS = [24, 30, 60]
+export const VALID_QUALITIES = ['fast', 'social', 'studio']
 
 export function validateRenderFormat(rawFormat) {
   const fmt = String(rawFormat || 'mp4').trim().toLowerCase()
@@ -20,6 +27,23 @@ export function validateRenderFormat(rawFormat) {
   return fmt
 }
 
+export function validateRenderFps(rawFps) {
+  if (rawFps === undefined || rawFps === null || rawFps === '') return 30
+  const fps = Number(rawFps)
+  if (!VALID_FPS.includes(fps)) {
+    throw new Error(`Unsupported fps "${rawFps}". Supported fps: ${VALID_FPS.join(', ')}`)
+  }
+  return fps
+}
+
+export function validateRenderQuality(rawQuality) {
+  const quality = String(rawQuality || 'social').trim().toLowerCase()
+  if (!VALID_QUALITIES.includes(quality)) {
+    throw new Error(`Unsupported render quality "${quality}". Supported qualities: ${VALID_QUALITIES.join(', ')}`)
+  }
+  return quality
+}
+
 const MIME_TYPES = {
   '.html': 'text/html; charset=utf-8',
   '.js': 'application/javascript; charset=utf-8',
@@ -130,29 +154,21 @@ export function startStaticServer(rootDir) {
   })
 }
 
-async function openStudioSession(opts = {}) {
-  const { chromium } = await loadPlaywright()
-  const chromePath = findChromeExecutable(opts.chromePath)
-
-  let staticSrv = null
-  let targetUrl = opts.studioUrl || process.env.OLO_STUDIO_URL || ''
-
-  if (!targetUrl) {
-    const publicDir = findPublicStudioDir(opts.publicDir)
-    if (publicDir) {
-      staticSrv = await startStaticServer(publicDir)
-      targetUrl = `${staticSrv.baseUrl}/studio/index.html`
-    } else {
-      targetUrl = 'https://www.olomni.com/studio'
-    }
-  }
+export function resolveDefaultAngleBackend() {
+  if (process.env.OLO_CHROME_ANGLE) return process.env.OLO_CHROME_ANGLE
+  if (process.platform === 'darwin') return 'metal'
+  if (process.platform === 'win32') return 'd3d11'
+  if (process.platform === 'linux') return 'vulkan'
+  return 'swiftshader'
+}
 
+async function launchStudioAttempt(chromium, chromePath, targetUrl, angleBackend, opts) {
   const browser = await chromium.launch({
     headless: true,
     ...(chromePath ? { executablePath: chromePath } : {}),
     args: [
       '--use-gl=angle',
-      '--use-angle=swiftshader',
+      `--use-angle=${angleBackend}`,
       '--enable-webgl',
       '--ignore-gpu-blocklist',
       '--autoplay-policy=no-user-gesture-required',
@@ -177,20 +193,120 @@ async function openStudioSession(opts = {}) {
       { timeout: opts.timeoutMs || 25000 },
     )
 
-    return { browser, context, page, staticSrv, targetUrl, chromePath }
+    const waitModelPromise = page.evaluate(async () => {
+      if (window.OloStudioBridge && typeof window.OloStudioBridge.waitForModelReady === 'function') {
+        await window.OloStudioBridge.waitForModelReady(12000)
+      }
+    })
+    if (angleBackend === 'swiftshader') {
+      await waitModelPromise.catch(() => {})
+    } else {
+      await waitModelPromise
+    }
+
+    return { browser, context, page, angleBackend }
   } catch (err) {
     await browser.close().catch(() => {})
-    if (staticSrv) await staticSrv.close().catch(() => {})
     throw err
   }
 }
 
-async function renderOnPage(page, opts) {
-  const compiled = compileSceneSpec(opts.sceneSpec || opts)
-  const format = validateRenderFormat(opts.format)
+async function openStudioSession(opts = {}) {
+  const { chromium } = await loadPlaywright()
+  const chromePath = findChromeExecutable(opts.chromePath)
 
-  if (opts.glbPath) {
-    const absGlb = path.resolve(opts.glbPath)
+  let staticSrv = null
+  let targetUrl = opts.studioUrl || process.env.OLO_STUDIO_URL || ''
+
+  if (!targetUrl) {
+    const publicDir = findPublicStudioDir(opts.publicDir)
+    if (publicDir) {
+      staticSrv = await startStaticServer(publicDir)
+      targetUrl = `${staticSrv.baseUrl}/studio/index.html`
+    } else {
+      console.error(
+        '[olo-studio-mcp] Warning: local public/studio directory not found; falling back to https://www.olomni.com/studio',
+      )
+      targetUrl = 'https://www.olomni.com/studio'
+    }
+  }
+
+  const primaryAngle = resolveDefaultAngleBackend()
+  try {
+    const attempt = await launchStudioAttempt(chromium, chromePath, targetUrl, primaryAngle, opts)
+    return { ...attempt, staticSrv, targetUrl, chromePath }
+  } catch (primaryErr) {
+    if (primaryAngle === 'swiftshader') {
+      if (staticSrv) await staticSrv.close().catch(() => {})
+      throw primaryErr
+    }
+    try {
+      const fallback = await launchStudioAttempt(chromium, chromePath, targetUrl, 'swiftshader', opts)
+      return { ...fallback, staticSrv, targetUrl, chromePath }
+    } catch (fallbackErr) {
+      if (staticSrv) await staticSrv.close().catch(() => {})
+      throw fallbackErr
+    }
+  }
+}
+
+async function synthesizeOfflineSpeechWavBase64(compiled) {
+  if (!compiled || !Array.isArray(compiled.beats)) return ''
+  const spoken = compiled.beats.map((b) => String((b && b.text) || '').trim()).filter(Boolean).join('. ')
+  if (!spoken) return ''
+  const isSpanish = /[áéíóúñ¿¡]|\b(hola|para|con|tu|marca|video|soy|listo|crear|desde)\b/i.test(spoken)
+  const tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'olo-tts-'))
+  const wavPath = path.join(tmpDir, 'speech.wav')
+  try {
+    if (process.platform === 'darwin') {
+      const voiceName = isSpanish ? 'Paulina' : 'Samantha'
+      const aiffPath = path.join(tmpDir, 'speech.aiff')
+      await execFileAsync('/usr/bin/say', ['-v', voiceName, '-o', aiffPath, spoken], { timeout: 15000 })
+      await execFileAsync('/usr/bin/afconvert', ['-f', 'WAVE', '-d', 'LEI16@48000', '-c', '1', aiffPath, wavPath], { timeout: 15000 })
+    } else if (process.platform === 'win32') {
+      const psScript = [
+        'Add-Type -AssemblyName System.Speech',
+        '$s = New-Object System.Speech.Synthesis.SpeechSynthesizer',
+        '$s.SetOutputToWaveFile($env:OLO_TTS_WAV)',
+        '$s.Speak($env:OLO_TTS_TEXT)',
+        '$s.Dispose()',
+      ].join('; ')
+      await execFileAsync(
+        'powershell.exe',
+        ['-NoProfile', '-NonInteractive', '-Command', psScript],
+        {
+          timeout: 15000,
+          env: { ...process.env, OLO_TTS_TEXT: spoken, OLO_TTS_WAV: wavPath },
+        },
+      )
+    } else if (process.platform === 'linux') {
+      const lang = isSpanish ? 'es' : 'en'
+      let synthesized = false
+      for (const bin of ['espeak-ng', 'espeak']) {
+        try {
+          await execFileAsync(bin, ['-v', lang, '-w', wavPath, spoken], { timeout: 15000 })
+          synthesized = true
+          break
+        } catch {
+          // try next available TTS binary
+        }
+      }
+      if (!synthesized) return ''
+    } else {
+      return ''
+    }
+    const wavBuf = await fsp.readFile(wavPath)
+    return wavBuf.toString('base64')
+  } catch {
+    return ''
+  } finally {
+    await fsp.rm(tmpDir, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+async function loadGlbOnPage(page, { glbPath, glbUrl } = {}) {
+  if (glbPath) {
+    const absGlb = path.resolve(glbPath)
     const buf = await fsp.readFile(absGlb)
     const b64 = buf.toString('base64')
     await page.evaluate(
@@ -202,35 +318,94 @@ async function renderOnPage(page, opts) {
       },
       { base64: b64, fileName: path.basename(absGlb) },
     )
-  } else if (opts.glbUrl) {
+  } else if (glbUrl) {
     await page.evaluate(async (url) => {
       await window.OloStudioBridge.loadGlbFromUrl(url)
-    }, opts.glbUrl)
+    }, glbUrl)
   }
+}
+
+async function renderOnPage(page, opts) {
+  const compileInput = opts.sceneSpec
+    ? {
+        ...opts.sceneSpec,
+        ...(opts.voice !== undefined ? { voice: opts.voice } : {}),
+        ...(opts.voiceId !== undefined ? { voiceId: opts.voiceId } : {}),
+        ...(opts.captions !== undefined ? { captions: opts.captions } : {}),
+        ...(opts.pipPath !== undefined ? { pipPath: opts.pipPath } : {}),
+        ...(opts.pipUrl !== undefined ? { pipUrl: opts.pipUrl } : {}),
+      }
+    : opts
+  const compiled = compileSceneSpec(compileInput)
+  const format = validateRenderFormat(opts.format)
+  const requestedFps = validateRenderFps(opts.fps ?? compiled.fps)
+  const requestedQuality = validateRenderQuality(opts.quality ?? compiled.quality)
+  const scenePayload = { ...compiled, fps: requestedFps, quality: requestedQuality }
+  const resolvedApiKey = opts.apiKey || process.env.OLO_STUDIO_API_KEY
+  if (resolvedApiKey) {
+    scenePayload.apiKey = resolvedApiKey
+  }
+  if (!scenePayload.customAudioWavBase64 && scenePayload.voice !== 'synth') {
+    const wavB64 = await synthesizeOfflineSpeechWavBase64(scenePayload)
+    if (wavB64) {
+      if (resolvedApiKey) {
+        scenePayload.fallbackAudioWavBase64 = wavB64
+      } else {
+        scenePayload.customAudioWavBase64 = wavB64
+      }
+    }
+  }
+
+  await loadGlbOnPage(page, opts)
 
   const exportResult = await page.evaluate(
     async ({ scene, fmt }) => {
       const res = await window.OloStudioBridge.exportSceneBuffer(scene, fmt)
-      const bytes = Array.from(new Uint8Array(res.arrayBuffer))
+      let base64 = ''
+      if (typeof FileReader !== 'undefined') {
+        base64 = await new Promise((resolve, reject) => {
+          const reader = new FileReader()
+          reader.onload = () => {
+            const dataUrl = String(reader.result || '')
+            const marker = 'base64,'
+            const idx = dataUrl.indexOf(marker)
+            resolve(idx >= 0 ? dataUrl.slice(idx + marker.length) : dataUrl)
+          }
+          reader.onerror = () => reject(reader.error || new Error('FileReader failed'))
+          reader.readAsDataURL(new Blob([res.arrayBuffer]))
+        })
+      } else {
+        const u8 = new Uint8Array(res.arrayBuffer)
+        const CHUNK = 0x8000
+        const parts = []
+        for (let i = 0; i < u8.length; i += CHUNK) {
+          parts.push(String.fromCharCode.apply(null, u8.subarray(i, i + CHUNK)))
+        }
+        base64 = btoa(parts.join(''))
+      }
       return {
-        bytes,
+        base64,
         mimeType: res.mimeType,
         ext: res.ext,
         durationSec: res.durationSec,
         watermarked: res.watermarked,
+        beats: Array.isArray(res.beats) ? res.beats : null,
       }
     },
-    { scene: compiled, fmt: format },
+    { scene: scenePayload, fmt: format },
   )
 
-  const buffer = Buffer.from(exportResult.bytes)
+  const buffer = Buffer.from(exportResult.base64, 'base64')
   const outPath = path.resolve(opts.outputPath || `olo-render-${compiled.sceneHash}.${exportResult.ext || 'mp4'}`)
   await fsp.mkdir(path.dirname(outPath), { recursive: true })
   await fsp.writeFile(outPath, buffer)
 
   let srtPath = null
   if (opts.srt !== false) {
-    const srtContent = generateSrt(compiled)
+    const srtContent = generateSrt({
+      ...compiled,
+      beats: exportResult.beats || compiled.beats,
+    })
     if (srtContent) {
       const outputBase = outPath.slice(0, outPath.length - path.extname(outPath).length)
       srtPath = `${outputBase}.srt`
@@ -254,6 +429,8 @@ async function renderOnPage(page, opts) {
 
 export async function renderVideoWithBrowser(opts = {}) {
   validateRenderFormat(opts.format)
+  if (opts.fps !== undefined) validateRenderFps(opts.fps)
+  if (opts.quality !== undefined) validateRenderQuality(opts.quality)
   const session = await openStudioSession(opts)
   try {
     const res = await renderOnPage(session.page, opts)
@@ -270,14 +447,24 @@ export async function renderVideoWithBrowser(opts = {}) {
 
 export async function renderBatchWithBrowser(opts = {}) {
   const format = validateRenderFormat(opts.format)
-  let variants = Array.isArray(opts.variants) ? opts.variants : []
+  const batchFps = opts.fps !== undefined ? validateRenderFps(opts.fps) : undefined
+  const batchQuality = opts.quality !== undefined ? validateRenderQuality(opts.quality) : undefined
+  const usedDirectVariants = Array.isArray(opts.variants) && opts.variants.length > 0
+  let variants = usedDirectVariants ? opts.variants : []
 
   if (variants.length === 0) {
     let csvContent = opts.csv
     if (!csvContent && opts.csvPath) {
       csvContent = await fsp.readFile(path.resolve(opts.csvPath), 'utf8')
     }
-    variants = parseBatchInput({ specs: opts.specs, csv: csvContent })
+    const batchDefaults = {
+      ...(opts.voice !== undefined ? { voice: opts.voice } : {}),
+      ...(opts.voiceId !== undefined ? { voiceId: opts.voiceId } : {}),
+      ...(opts.captions !== undefined ? { captions: opts.captions } : {}),
+      ...(opts.pipPath !== undefined ? { pipPath: opts.pipPath } : {}),
+      ...(opts.pipUrl !== undefined ? { pipUrl: opts.pipUrl } : {}),
+    }
+    variants = parseBatchInput({ specs: opts.specs, csv: csvContent, defaults: batchDefaults })
   }
 
   if (variants.length === 0) {
@@ -290,15 +477,49 @@ export async function renderBatchWithBrowser(opts = {}) {
   const session = await openStudioSession(opts)
   const results = []
   try {
+    const hasBatchGlb = Boolean(opts.glbPath || opts.glbUrl)
+    const hasVariantGlbOverride = variants.some((v) => Boolean(v.glbPath || v.glbUrl))
+    const hoistSharedGlb = hasBatchGlb && !hasVariantGlbOverride
+    if (hoistSharedGlb) {
+      await loadGlbOnPage(session.page, { glbPath: opts.glbPath, glbUrl: opts.glbUrl })
+    }
+
+    let activeGlbKey = hoistSharedGlb
+      ? (opts.glbPath ? `path:${path.resolve(opts.glbPath)}` : `url:${opts.glbUrl}`)
+      : null
+
     for (const variant of variants) {
       const outPath = path.join(outputDir, `${variant.outputName}.${ext}`)
+      const effectiveGlbPath = variant.glbPath || (!variant.glbUrl ? opts.glbPath : undefined)
+      const effectiveGlbUrl = variant.glbUrl || (!variant.glbPath ? opts.glbUrl : undefined)
+      const effectiveGlbKey = effectiveGlbPath
+        ? `path:${path.resolve(effectiveGlbPath)}`
+        : effectiveGlbUrl
+          ? `url:${effectiveGlbUrl}`
+          : null
+      const needsGlbLoad = Boolean(effectiveGlbKey && effectiveGlbKey !== activeGlbKey)
+      if (needsGlbLoad) {
+        activeGlbKey = effectiveGlbKey
+      }
+
       const rendered = await renderOnPage(session.page, {
         sceneSpec: variant.sceneSpec,
         format,
+        fps: variant.fps ?? batchFps,
+        quality: variant.quality ?? batchQuality,
         srt: opts.srt,
         outputPath: outPath,
-        glbUrl: variant.glbUrl || opts.glbUrl,
-        glbPath: variant.glbPath || opts.glbPath,
+        apiKey: variant.apiKey || opts.apiKey,
+        ...(usedDirectVariants
+          ? {
+              voice: variant.voice ?? (variant.sceneSpec?.voice === undefined ? opts.voice : undefined),
+              voiceId: variant.voiceId ?? (variant.sceneSpec?.voiceId === undefined ? opts.voiceId : undefined),
+              captions: variant.captions ?? (variant.sceneSpec?.captions === undefined ? opts.captions : undefined),
+              pipPath: variant.pipPath ?? (!variant.sceneSpec?.pipMeta ? opts.pipPath : undefined),
+              pipUrl: variant.pipUrl ?? (!variant.sceneSpec?.pipMeta ? opts.pipUrl : undefined),
+            }
+          : {}),
+        ...(needsGlbLoad ? { glbUrl: effectiveGlbUrl, glbPath: effectiveGlbPath } : {}),
       })
       results.push({
         index: variant.index,

package/src/server.js

@@ -1,11 +1,16 @@
 /**
- * @olomni/studio-mcp — Local-first MCP Server (JSON-RPC 2.0 over stdio)
+ * @olo-studio/studio-mcp — Local-first MCP Server (JSON-RPC 2.0 over stdio)
  * Registers the 7 canonical Olomni Studio tools via @modelcontextprotocol/sdk.
  */
+import fs from 'node:fs'
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod'
 import { getEntitlements, generateScript, manageVoiceClones } from './api-client.js'
+
+const PKG_VERSION = JSON.parse(
+  fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version
 import {
   compileSceneSpec,
   buildPublishEmbed,
@@ -20,7 +25,7 @@ import {
   FINISH_ALIASES,
   SCENARIO_ALIASES,
 } from './compiler.js'
-import { VALID_FORMATS, renderVideoWithBrowser, renderBatchWithBrowser } from './renderer.js'
+import { VALID_FORMATS, VALID_QUALITIES, renderVideoWithBrowser, renderBatchWithBrowser } from './renderer.js'
 
 function enumWithAliases(canonical, aliases, label) {
   return z
@@ -43,8 +48,8 @@ function jsonToolResult(payload, isError = false) {
 
 export function createStudioMcpServer(serverOpts = {}) {
   const server = new McpServer({
-    name: '@olomni/studio-mcp',
-    version: '1.0.0',
+    name: '@olo-studio/studio-mcp',
+    version: PKG_VERSION,
   })
 
   // 1. olo_get_entitlements
@@ -131,6 +136,8 @@ export function createStudioMcpServer(serverOpts = {}) {
     {
       outputPath: z.string().min(1).describe('Destination file path for the rendered video (e.g. ./out/demo.mp4).'),
       format: z.enum(VALID_FORMATS).default('mp4').describe('Output container/mode: mp4, webm, webm_alpha, alpha, chroma.'),
+      fps: z.union([z.literal(24), z.literal(30), z.literal(60)]).default(30).describe('Frames per second: 24, 30, or 60 (default: 30).'),
+      quality: z.enum(VALID_QUALITIES).default('social').describe('Render quality preset: fast, social, or studio (default: social).'),
       srt: z.boolean().default(true).describe('Write <outputBase>.srt timed captions alongside the video (default: true).'),
       sceneSpec: z.record(z.any()).optional().describe('Pre-compiled olomni.studio.scene.v1 JSON.'),
       script: z.string().optional().describe('Raw script text if sceneSpec is omitted.'),
@@ -139,14 +146,23 @@ export function createStudioMcpServer(serverOpts = {}) {
       tint: z.string().optional(),
       finish: z.string().optional(),
       scenario: z.string().optional(),
+      voice: z.string().optional().describe('Voice preset or TTS voice name.'),
+      voiceId: z.string().optional().describe('Cloned voice ID for neural TTS.'),
+      captions: z.boolean().optional().describe('Include timed captions/subtitles (default: true).'),
+      pipPath: z.string().optional().describe('Local file path for Picture-in-Picture media (png, jpg, webp, mp4, webm).'),
+      pipUrl: z.string().optional().describe('Remote URL for Picture-in-Picture media.'),
       glbUrl: z.string().optional().describe('Optional custom mascot .glb/.gltf URL.'),
       glbPath: z.string().optional().describe('Optional local .glb/.gltf file path.'),
       studioUrl: z.string().optional().describe('Optional Studio URL (defaults to local static server or https://www.olomni.com/studio).'),
+      apiKey: z.string().optional().describe('Optional olo_pat_... token (defaults to OLO_STUDIO_API_KEY env var).'),
       timeoutMs: z.number().int().positive().optional(),
     },
     async (args) => {
       try {
-        const result = await renderVideoWithBrowser(args)
+        const result = await renderVideoWithBrowser({
+          ...args,
+          apiKey: args.apiKey || serverOpts.apiKey,
+        })
         return jsonToolResult(result)
       } catch (err) {
         return jsonToolResult(
@@ -164,19 +180,30 @@ export function createStudioMcpServer(serverOpts = {}) {
     {
       outputDir: z.string().min(1).describe('Directory where rendered variant videos will be saved.'),
       format: z.enum(VALID_FORMATS).default('mp4').describe('Output container/mode: mp4, webm, webm_alpha, alpha, chroma.'),
+      fps: z.union([z.literal(24), z.literal(30), z.literal(60)]).default(30).describe('Frames per second: 24, 30, or 60 (default: 30).'),
+      quality: z.enum(VALID_QUALITIES).default('social').describe('Render quality preset: fast, social, or studio (default: social).'),
       specs: z.array(z.record(z.any())).optional().describe('Array of SceneSpec or compile-option objects.'),
       csv: z.string().optional().describe('CSV string with header row (e.g. title,language,script,wear,tint,scenario,voice,voiceId,outputName).'),
       csvPath: z.string().optional().describe('Path to a local CSV file with variant rows.'),
       zip: z.boolean().default(true).describe('Package rendered videos, .srt files, and manifest.json into <outputDir>/batch.zip (default: true).'),
       srt: z.boolean().default(true).describe('Write .srt timed captions alongside each video (default: true).'),
+      voice: z.string().optional().describe('Default voice preset or TTS voice name for variants.'),
+      voiceId: z.string().optional().describe('Default cloned voice ID for neural TTS.'),
+      captions: z.boolean().optional().describe('Include timed captions/subtitles by default (default: true).'),
+      pipPath: z.string().optional().describe('Default local file path for Picture-in-Picture media (png, jpg, webp, mp4, webm).'),
+      pipUrl: z.string().optional().describe('Default remote URL for Picture-in-Picture media.'),
       glbUrl: z.string().optional(),
       glbPath: z.string().optional(),
       studioUrl: z.string().optional(),
+      apiKey: z.string().optional().describe('Optional olo_pat_... token (defaults to OLO_STUDIO_API_KEY env var).'),
       timeoutMs: z.number().int().positive().optional(),
     },
     async (args) => {
       try {
-        const result = await renderBatchWithBrowser(args)
+        const result = await renderBatchWithBrowser({
+          ...args,
+          apiKey: args.apiKey || serverOpts.apiKey,
+        })
         return jsonToolResult(result)
       } catch (err) {
         return jsonToolResult(