@jambonz/speech-utils 1.0.19 → 1.0.22

package/.github/workflows/ci.yml

@@ -11,11 +11,11 @@ jobs:
       id-token: write   # required to request the GitHub OIDC token for AWS
       contents: read
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
         with:
-          node-version: '20'
-      - uses: aws-actions/configure-aws-credentials@v4
+          node-version: '22'
+      - uses: aws-actions/configure-aws-credentials@v6
         with:
           role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
           aws-region: us-east-1

package/.github/workflows/publish.yml

@@ -12,8 +12,8 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
         with:
           node-version: lts/*
           registry-url: 'https://registry.npmjs.org'

package/lib/synth-audio.js

@@ -81,7 +81,7 @@ async function synthAudio(client, createHash, retrieveHash, logger, stats, { acc
 
   assert.ok(['google', 'aws', 'polly', 'microsoft', 'wellsaid', 'nvidia', 'elevenlabs',
     'whisper', 'deepgram', 'deepgramflux', 'rimelabs', 'cartesia', 'gradium', 'kugelaudio', 'nineninesix', 'inworld',
-    'resemble', 'murf', 'xai', 'fishaudio']
+    'resemble', 'murf', 'xai', 'fishaudio', 'speechify', 'giggy', 'svara']
     .includes(vendor) ||
   vendor.startsWith('custom'),
   `synthAudio supported vendors are google, aws, microsoft, nvidia and wellsaid ..etc, not ${vendor}`);
@@ -139,6 +139,15 @@ async function synthAudio(client, createHash, retrieveHash, logger, stats, { acc
   } else if ('gradium' === vendor) {
     assert.ok(voice, 'synthAudio requires voice when gradium is used');
     assert.ok(credentials.api_key, 'synthAudio requires api_key when gradium is used');
+  } else if ('speechify' === vendor) {
+    assert.ok(voice, 'synthAudio requires voice when speechify is used');
+    assert.ok(credentials.api_key, 'synthAudio requires api_key when speechify is used');
+  } else if ('giggy' === vendor) {
+    assert.ok(voice, 'synthAudio requires voice when giggy is used');
+    assert.ok(credentials.api_key, 'synthAudio requires api_key when giggy is used');
+  } else if ('svara' === vendor) {
+    assert.ok(voice, 'synthAudio requires voice when svara is used');
+    assert.ok(credentials.api_key, 'synthAudio requires api_key when svara is used');
   } else if ('kugelaudio' === vendor) {
     assert.ok(voice, 'synthAudio requires voice when kugelaudio is used');
     assert.ok(credentials.api_key, 'synthAudio requires api_key when kugelaudio is used');
@@ -242,6 +251,21 @@ async function synthAudio(client, createHash, retrieveHash, logger, stats, { acc
           credentials, options, stats, language, voice, key, text, renderForCaching, disableTtsStreaming,
           disableTtsCache});
         break;
+      case 'speechify':
+        audioData = await synthSpeechify(logger, {
+          credentials, options, stats, language, voice, key, text, renderForCaching, disableTtsStreaming,
+          disableTtsCache});
+        break;
+      case 'giggy':
+        audioData = await synthGiggy(logger, {
+          credentials, options, stats, voice, key, text, renderForCaching, disableTtsStreaming,
+          disableTtsCache});
+        break;
+      case 'svara':
+        audioData = await synthSvara(logger, {
+          credentials, options, stats, language, voice, key, text, renderForCaching, disableTtsStreaming,
+          disableTtsCache});
+        break;
       case 'nineninesix':
         audioData = await synthNineninesix(logger, {
           credentials, stats, language, voice, key, text, renderForCaching, disableTtsStreaming,
@@ -1369,14 +1393,10 @@ const synthCartesia = async(logger, {
 
     // omit a control unless explicitly provided (0 is a valid value, so test for nullish only)
     const has = (v) => v !== null && v !== undefined;
-    /* Voice controls are model-family specific:
-       - sonic-2 takes `experimentalControls` (emotion is an array, no volume).
-       - sonic-3 family (sonic-3, sonic-3.5, pinned sonic-3.x snapshots) takes
-         `generationConfig` (emotion is a string, volume supported). Match the same
-         "starts with sonic-3" predicate the freeswitch streaming module uses
-         (mod_cartesia_tts_streaming: strncmp(model_id, "sonic-3", ...)), so cached
-         and streamed synthesis behave identically.
-       Older models (sonic, sonic-english, sonic-multilingual, sonic-2024-*) take neither. */
+    /* Voice controls (speed, emotion, volume) go in `generationConfig`, which only the
+       sonic-3 family (sonic-3, sonic-3.5, sonic-3.6, pinned sonic-3.x snapshots) accepts;
+       other models get no controls. mediajam uses the same "starts with sonic-3" check
+       (internal/tts/cartesia.go), so cached and streamed synthesis behave identically. */
     const isSonic3 = model_id?.startsWith('sonic-3');
     const mp3Stream = await client.tts.bytes({
       modelId: model_id,
@@ -1391,12 +1411,6 @@ const synthCartesia = async(logger, {
             id: voice
           }
         ),
-        ...(model_id === 'sonic-2' && (opts.speed || opts.emotion) && {
-          experimentalControls: {
-            ...(has(opts.speed) && {speed: opts.speed}),
-            ...(opts.emotion && {emotion: [opts.emotion]}),
-          }
-        }),
       },
       ...(isSonic3 && (has(opts.speed) || has(opts.emotion) || has(opts.volume)) && {
         generationConfig: {
@@ -1602,6 +1616,253 @@ const synthKugelaudio = async(logger, {
   }
 };
 
+/* simba-3.2 is English only; with no model set, other languages get simba-3.0 */
+const speechifyModel = (model_id, language) => {
+  if (model_id) return model_id;
+  return !language || /^en/i.test(language) ? 'simba-3.2' : 'simba-3.0';
+};
+const synthSpeechify = async(logger, {
+  credentials, options, stats, language, voice, key, text, renderForCaching, disableTtsStreaming,
+  disableTtsCache
+}) => {
+  const {api_key, model_id} = credentials;
+  let credOptions = credentials.options || {};
+  if (typeof credOptions === 'string') {
+    try {
+      credOptions = JSON.parse(credOptions);
+    } catch {
+      credOptions = {};
+    }
+  }
+  const {api_uri, loudness_normalization, text_normalization} = {...credOptions, ...options};
+  const isSet = (v) => v !== null && v !== undefined;
+  const model = speechifyModel(options?.model_id || model_id, language);
+
+  /* default to using the streaming interface, unless disabled by env var OR we want just a cache file */
+  if (!JAMBONES_DISABLE_TTS_STREAMING && !renderForCaching && !disableTtsStreaming) {
+    let params = '{';
+    params += `api_key=${api_key}`;
+    params += `,playback_id=${key}`;
+    params += ',vendor=speechify';
+    params += `,voice=${voice}`;
+    params += `,write_cache_file=${disableTtsCache ? 0 : 1}`;
+    params += `,model_id=${model}`;
+    if (language) params += `,language=${language}`;
+    if (api_uri) params += `,api_uri=${api_uri}`;
+    if (isSet(loudness_normalization)) params += `,loudness_normalization=${loudness_normalization}`;
+    if (isSet(text_normalization)) params += `,text_normalization=${text_normalization}`;
+    params += '}';
+
+    return {
+      filePath: `say:${params}${text.replace(/\n/g, ' ').replace(/\r/g, ' ')}`,
+      servedFromCache: false,
+      rtt: 0
+    };
+  }
+
+  try {
+    /* other pcm rates are mislabelled 24 kHz on workspaces pinned before 2026-09-30 */
+    const sampleRate = 24000;
+    const host = (api_uri || 'api.speechify.ai').replace(/^[a-z]+:\/\//, '').replace(/\/$/, '');
+    const post = bent(`https://${host}`, 'POST', 'buffer', {
+      'Authorization': `Bearer ${api_key}`,
+      'Content-Type': 'application/json',
+      'Speechify-Caller': 'jambonz'
+    });
+    const toBool = (v) => v === true || v === 'true';
+    const speechOptions = {
+      ...(isSet(loudness_normalization) && {loudness_normalization: toBool(loudness_normalization)}),
+      ...(isSet(text_normalization) && {text_normalization: toBool(text_normalization)})
+    };
+    const audioContent = await post('/v1/audio/stream', {
+      input: text,
+      voice_id: voice,
+      model,
+      output_format: `pcm_${sampleRate}`,
+      ...(language && {language}),
+      ...(Object.keys(speechOptions).length && {options: speechOptions})
+    });
+    return {
+      audioContent,
+      extension: 'r24',
+      sampleRate
+    };
+  } catch (err) {
+    logger.info({err}, 'synth speechify returned error');
+    stats.increment('tts.count', ['vendor:speechify', 'accepted:no']);
+    throw err;
+  }
+};
+
+/* language_code is never sent: Giggy rejects one that differs from the voice's own */
+const synthGiggy = async(logger, {
+  credentials, options, stats, voice, key, text, renderForCaching, disableTtsStreaming,
+  disableTtsCache
+}) => {
+  const {api_key, model_id} = credentials;
+  let credOptions = credentials.options || {};
+  if (typeof credOptions === 'string') {
+    try {
+      credOptions = JSON.parse(credOptions);
+    } catch {
+      credOptions = {};
+    }
+  }
+  const {api_uri, speed, seed} = {...credOptions, ...options};
+  const isSet = (v) => v !== null && v !== undefined;
+  const model = options?.model_id || model_id || 'giggyspeech';
+
+  /* default to using the streaming interface, unless disabled by env var OR we want just a cache file */
+  if (!JAMBONES_DISABLE_TTS_STREAMING && !renderForCaching && !disableTtsStreaming) {
+    let params = '{';
+    params += `api_key=${api_key}`;
+    params += `,playback_id=${key}`;
+    params += ',vendor=giggy';
+    params += `,voice=${voice}`;
+    params += `,write_cache_file=${disableTtsCache ? 0 : 1}`;
+    params += `,model_id=${model}`;
+    if (api_uri) params += `,api_uri=${api_uri}`;
+    if (isSet(speed)) params += `,speed=${speed}`;
+    if (isSet(seed)) params += `,seed=${seed}`;
+    params += '}';
+
+    return {
+      filePath: `say:${params}${text.replace(/\n/g, ' ').replace(/\r/g, ' ')}`,
+      servedFromCache: false,
+      rtt: 0
+    };
+  }
+
+  try {
+    /* streaming mode is the only one that returns raw pcm (fast/batch are mp3) */
+    const sampleRate = 24000;
+    const host = (api_uri || 'giggy.ai').replace(/^[a-z]+:\/\//, '').replace(/\/$/, '');
+    const post = bent(`https://${host}`, 'POST', 'buffer', {
+      'xi-api-key': api_key,
+      'Content-Type': 'application/json'
+    });
+    const audioContent = await post('/v1/text-to-speech', {
+      text,
+      voice_id: voice,
+      model_id: model,
+      mode: 'streaming',
+      output_format: `pcm_${sampleRate}`,
+      ...(isSet(speed) && {voice_settings: {speed: Number(speed)}}),
+      ...(isSet(seed) && {seed: Number(seed)})
+    });
+    return {
+      audioContent,
+      extension: 'r24',
+      sampleRate
+    };
+  } catch (err) {
+    logger.info({err}, 'synth giggy returned error');
+    stats.increment('tts.count', ['vendor:giggy', 'accepted:no']);
+    throw err;
+  }
+};
+
+const synthSvara = async(logger, {
+  credentials, options, stats, language, voice, key, text, renderForCaching, disableTtsStreaming,
+  disableTtsCache
+}) => {
+  const {api_key, model_id} = credentials;
+  let credOptions = credentials.options || {};
+  if (typeof credOptions === 'string') {
+    try {
+      credOptions = JSON.parse(credOptions);
+    } catch {
+      credOptions = {};
+    }
+  }
+  const {
+    api_uri, speed, pronunciation_dictionary_id, normalize, temperature, top_p, top_k, min_p,
+    repetition_penalty, presence_penalty, max_tokens, chunk_size, buffer_ms, chunk_codes
+  } = {...credOptions, ...options};
+  const isSet = (v) => v !== null && v !== undefined;
+  const model = options?.model_id || model_id || 'svara-tts-turbo';
+
+  /* default to using the streaming interface, unless disabled by env var OR we want just a cache file */
+  if (!JAMBONES_DISABLE_TTS_STREAMING && !renderForCaching && !disableTtsStreaming) {
+    let params = '{';
+    params += `api_key=${api_key}`;
+    params += `,playback_id=${key}`;
+    params += ',vendor=svara';
+    params += `,voice=${voice}`;
+    params += `,write_cache_file=${disableTtsCache ? 0 : 1}`;
+    params += `,model_id=${model}`;
+    if (language) params += `,language=${language}`;
+    if (api_uri) params += `,endpoint=${api_uri}`;
+    if (isSet(speed)) params += `,speed=${speed}`;
+    if (pronunciation_dictionary_id) params += `,pronunciation_dictionary_id=${pronunciation_dictionary_id}`;
+    if (isSet(normalize)) params += `,normalize=${normalize}`;
+    if (isSet(temperature)) params += `,temperature=${temperature}`;
+    if (isSet(top_p)) params += `,top_p=${top_p}`;
+    if (isSet(top_k)) params += `,top_k=${top_k}`;
+    if (isSet(min_p)) params += `,min_p=${min_p}`;
+    if (isSet(repetition_penalty)) params += `,repetition_penalty=${repetition_penalty}`;
+    if (isSet(presence_penalty)) params += `,presence_penalty=${presence_penalty}`;
+    if (isSet(max_tokens)) params += `,max_tokens=${max_tokens}`;
+    if (isSet(chunk_size)) params += `,chunk_size=${chunk_size}`;
+    if (isSet(buffer_ms)) params += `,buffer_ms=${buffer_ms}`;
+    if (isSet(chunk_codes)) params += `,chunk_codes=${chunk_codes}`;
+    params += '}';
+
+    return {
+      filePath: `say:${params}${text.replace(/\n/g, ' ').replace(/\r/g, ' ')}`,
+      servedFromCache: false,
+      rtt: 0
+    };
+  }
+
+  try {
+    const host = (api_uri || 'api.kenpathlabs.com').replace(/^[a-z]+:\/\//, '').replace(/\/$/, '');
+    const post = bent(`https://${host}`, 'POST', 'buffer', {
+      'Authorization': `Bearer ${api_key}`,
+      'Content-Type': 'application/json'
+    });
+    const audioContent = await post('/v1/audio/speech', {
+      input: text,
+      voice,
+      model,
+      response_format: 'wav',
+      sample_rate: 8000,
+      ...(language && {lang: language}),
+      ...(isSet(speed) && {speed: Number(speed)}),
+      ...(pronunciation_dictionary_id && {pronunciation_dictionary_id}),
+      ...(isSet(normalize) && {normalize: normalize === true || normalize === 'true'}),
+      ...(isSet(temperature) && {temperature: Number(temperature)}),
+      ...(isSet(top_p) && {top_p: Number(top_p)}),
+      ...(isSet(top_k) && {top_k: Number(top_k)}),
+      ...(isSet(min_p) && {min_p: Number(min_p)}),
+      ...(isSet(repetition_penalty) && {repetition_penalty: Number(repetition_penalty)}),
+      ...(isSet(presence_penalty) && {presence_penalty: Number(presence_penalty)}),
+      ...(isSet(max_tokens) && {max_tokens: Number(max_tokens)}),
+      ...(isSet(chunk_size) && {chunk_size: Number(chunk_size)}),
+      ...(isSet(buffer_ms) && {buffer_ms: Number(buffer_ms)}),
+      ...(isSet(chunk_codes) && {chunk_codes: Number(chunk_codes)})
+    });
+    return {
+      audioContent,
+      extension: 'wav',
+      sampleRate: 8000
+    };
+  } catch (err) {
+    /* errors are JSON {detail: {status, message}}; surface the body instead of 'undefined' */
+    if (err.name === 'StatusError' && typeof err.text === 'function') {
+      try {
+        const body = await err.text();
+        if (body) err.message = body;
+      } catch (readErr) {
+        logger.info({readErr}, 'synth svara: failed to read error response body');
+      }
+    }
+    logger.info({err}, 'synth svara returned error');
+    stats.increment('tts.count', ['vendor:svara', 'accepted:no']);
+    throw err;
+  }
+};
+
 /* nineninesix.ai — a Cartesia-compatible API, but only raw/wav come back
    (mp3 is rejected), so the cache render asks for wav rather than mp3. */
 /* fish.audio — msgpack websocket for streaming, and a POST endpoint for the cache

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@jambonz/speech-utils",
-  "version": "1.0.19",
+  "version": "1.0.22",
+  "engines": {
+    "node": ">=22"
+  },
   "description": "TTS-related speech utilities for jambonz",
   "main": "index.js",
   "author": "Dave Horton",
@@ -28,8 +31,8 @@
     "@aws-sdk/client-polly": "^3.496.0",
     "@aws-sdk/client-sts": "^3.496.0",
     "@cartesia/cartesia-js": "^2.2.7",
-    "@google-cloud/text-to-speech": "^6.4.0",
-    "@grpc/grpc-js": "^1.9.14",
+    "@google-cloud/text-to-speech": "^7.0.0",
+    "@grpc/grpc-js": "^1.14.5",
     "@jambonz/realtimedb-helpers": "^0.8.7",
     "bent": "^7.3.12",
     "debug": "^4.3.4",

package/test/synth.js

@@ -1041,10 +1041,9 @@ test('Cartesia speech synth tests', async(t) => {
       vendor: 'cartesia',
       credentials: {
         api_key: process.env.CARTESIA_API_KEY,
-        model_id: 'sonic-english',
+        model_id: 'sonic-3.6',
         options: JSON.stringify({
           speed: 1,
-          emotion: 'female_happy',
         })
       },
       language: 'en',
@@ -1120,6 +1119,93 @@ test('kugelaudio speech synth tests', async(t) => {
   client.quit();
 });
 
+test('speechify speech synth tests', async(t) => {
+  const fn = require('..');
+  const {synthAudio, client} = fn(opts, logger);
+
+  if (!process.env.SPEECHIFY_API_KEY) {
+    t.pass('skipping speechify speech synth tests since SPEECHIFY_API_KEY is not provided');
+    return t.end();
+  }
+  const text = 'Hi there and welcome to jambonz! ' + Date.now();
+  try {
+    const opts = await synthAudio(stats, {
+      vendor: 'speechify',
+      credentials: {
+        api_key: process.env.SPEECHIFY_API_KEY
+      },
+      language: 'en-US',
+      voice: 'geffen_32',
+      text,
+      renderForCaching: true
+    });
+    t.ok(!opts.servedFromCache, `successfully synthed speechify audio to ${opts.filePath}`);
+
+  } catch (err) {
+    console.error(JSON.stringify(err));
+    t.end(err);
+  }
+  client.quit();
+});
+
+test('giggy speech synth tests', async(t) => {
+  const fn = require('..');
+  const {synthAudio, client} = fn(opts, logger);
+
+  if (!process.env.GIGGY_API_KEY) {
+    t.pass('skipping giggy speech synth tests since GIGGY_API_KEY is not provided');
+    return t.end();
+  }
+  const text = 'Hi there and welcome to jambonz! ' + Date.now();
+  try {
+    const opts = await synthAudio(stats, {
+      vendor: 'giggy',
+      credentials: {
+        api_key: process.env.GIGGY_API_KEY
+      },
+      language: 'en-US',
+      voice: process.env.GIGGY_VOICE_ID || '8f5aee7d-dd96-41c4-b04f-19bff046b02a',
+      text,
+      renderForCaching: true
+    });
+    t.ok(!opts.servedFromCache, `successfully synthed giggy audio to ${opts.filePath}`);
+
+  } catch (err) {
+    console.error(JSON.stringify(err));
+    t.end(err);
+  }
+  client.quit();
+});
+
+test('svara speech synth tests', async(t) => {
+  const fn = require('..');
+  const {synthAudio, client} = fn(opts, logger);
+
+  if (!process.env.SVARA_API_KEY) {
+    t.pass('skipping svara speech synth tests since SVARA_API_KEY is not provided');
+    return t.end();
+  }
+  const text = 'Hi there and welcome to jambonz! ' + Date.now();
+  try {
+    const opts = await synthAudio(stats, {
+      vendor: 'svara',
+      credentials: {
+        api_key: process.env.SVARA_API_KEY
+      },
+      language: 'en-US',
+      voice: process.env.SVARA_VOICE_ID || 'sv_a5thzx8v',
+      text,
+      renderForCaching: true
+    });
+    t.ok(!opts.servedFromCache, `successfully synthed svara audio to ${opts.filePath}`);
+
+  } catch (err) {
+    console.error(JSON.stringify(err));
+    t.end(err);
+  }
+  client.quit();
+});
+
 test('fishaudio speech synth tests', async(t) => {
   const fn = require('..');
   const {synthAudio, client} = fn(opts, logger);