1.0.12

Streaming arm returns a say: url for the mediajam dialect; the cache-render
arm posts to /api/post/speech/tts with only_audio and pcm_8000, which is bare
r8 samples and avoids gradium's streaming wav header (0xffffffff RIFF size).

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,84 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+`@jambonz/speech-utils` is a Node.js library providing TTS (Text-to-Speech) utilities for the jambonz CPaaS platform. It handles speech synthesis with caching through Redis and supports multiple TTS vendors.
+
+## Commands
+
+```bash
+# Run tests (requires Docker for Redis)
+npm test
+
+# Run linter
+npm run jslint
+
+# Auto-fix lint issues
+npm run jslint:fix
+
+# Generate coverage report
+npm run coverage
+```
+
+## Testing
+
+Tests use `tape` and require Redis. The test harness automatically starts/stops Redis via Docker Compose (`test/docker-compose-testbed.yaml`).
+
+Most tests are conditional based on environment variables for vendor credentials:
+- `GCP_FILE` or `GCP_JSON_KEY` - Google TTS
+- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` - AWS Polly
+- `MICROSOFT_API_KEY`, `MICROSOFT_REGION` - Azure TTS
+- `ELEVENLABS_API_KEY`, `ELEVENLABS_VOICE_ID`, `ELEVENLABS_MODEL_ID` - ElevenLabs
+- `OPENAI_API_KEY` - OpenAI Whisper TTS
+- And others per vendor
+
+Redis config is in `config/test.json` (port 3379).
+
+## Architecture
+
+### Entry Point
+
+`index.js` exports a factory function that takes Redis options and a logger, returning an object with these methods:
+- `synthAudio` - Main synthesis function
+- `getTtsVoices` - List available voices for a vendor
+- `purgeTtsCache` / `getTtsSize` / `addFileToCache` - Cache management
+- `getAwsAuthToken` - Token management
+
+### Core Module: `lib/synth-audio.js`
+
+The `synthAudio` function handles synthesis for all vendors. Key behaviors:
+1. **Cache check**: Generates SHA1 hash key from (vendor, language, voice, engine, model, text, instructions)
+2. **Streaming vs non-streaming**: When `JAMBONES_DISABLE_TTS_STREAMING` is not set and `renderForCaching=false`, returns `say:{params}text` format for FreeSWITCH streaming playback instead of generating files
+3. **Vendor dispatch**: Switch statement routes to vendor-specific synth functions (`synthGoogle`, `synthPolly`, `synthMicrosoft`, etc.)
+4. **Caching**: Stores audio as base64 JSON in Redis with configurable TTL (default 4 hours)
+
+### Supported Vendors
+
+google, aws/polly, microsoft/azure, nvidia (Riva), wellsaid, elevenlabs, cartesia, inworld, rimelabs, whisper (OpenAI), deepgram, resemble, custom:*
+
+### gRPC Stubs
+
+`stubs/riva/` contains generated protobuf/gRPC code for NVIDIA Riva.
+
+## Environment Variables
+
+Key configuration via env vars (see `lib/config.js`):
+- `JAMBONES_DISABLE_TTS_STREAMING` - Force non-streaming mode
+- `JAMBONES_DISABLE_AZURE_TTS_STREAMING` - Azure-specific streaming disable
+- `JAMBONES_TTS_CACHE_DURATION_MINS` - Cache TTL in minutes (default: 240)
+- `JAMBONES_TTS_TRIM_SILENCE` - Trim trailing silence from audio
+- `JAMBONES_TMP_FOLDER` - Temp folder for audio files (default: /tmp)
+- `JAMBONES_HTTP_PROXY_IP`, `JAMBONES_HTTP_PROXY_PORT` - HTTP proxy for Azure
+- `JAMBONES_AZURE_ENABLE_SSML` - Force SSML wrapper for Azure plain text
+
+## Key Dependencies
+
+- `@jambonz/realtimedb-helpers` - Redis client and hash utilities
+- `@google-cloud/text-to-speech` - Google TTS
+- `@aws-sdk/client-polly` - AWS Polly
+- `microsoft-cognitiveservices-speech-sdk` - Azure TTS
+- `@grpc/grpc-js` - gRPC for Riva
+- `openai` - OpenAI Whisper TTS
+- `bent` - HTTP client for REST-based vendors

lib/synth-audio.js

@@ -80,7 +80,8 @@ async function synthAudio(client, createHash, retrieveHash, logger, stats, { acc
   logger = logger || noopLogger;
 
   assert.ok(['google', 'aws', 'polly', 'microsoft', 'wellsaid', 'nvidia', 'elevenlabs',
-    'whisper', 'deepgram', 'deepgramflux', 'rimelabs', 'cartesia', 'inworld', 'resemble', 'murf', 'xai']
+    'whisper', 'deepgram', 'deepgramflux', 'rimelabs', 'cartesia', 'gradium', 'nineninesix', 'inworld', 'resemble',
+    'murf', 'xai']
     .includes(vendor) ||
   vendor.startsWith('custom'),
   `synthAudio supported vendors are google, aws, microsoft, nvidia and wellsaid ..etc, not ${vendor}`);
@@ -135,6 +136,13 @@ async function synthAudio(client, createHash, retrieveHash, logger, stats, { acc
   } else if ('cartesia' === vendor) {
     assert.ok(credentials.api_key, 'synthAudio requires api_key when cartesia is used');
     assert.ok(credentials.model_id, 'synthAudio requires model_id when cartesia is used');
+  } 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 ('nineninesix' === vendor) {
+    assert.ok(voice, 'synthAudio requires voice when nineninesix is used');
+    assert.ok(credentials.api_key, 'synthAudio requires api_key when nineninesix is used');
+    assert.ok(credentials.model_id, 'synthAudio requires model_id when nineninesix is used');
   } else if ('murf' === vendor) {
     assert.ok(voice, 'synthAudio requires voice when murf is used');
     assert.ok(credentials.api_key, 'synthAudio requires api_key when murf is used');
@@ -212,6 +220,16 @@ async function synthAudio(client, createHash, retrieveHash, logger, stats, { acc
           credentials, options, stats, language, voice, key, text, renderForCaching, disableTtsStreaming,
           disableTtsCache});
         break;
+      case 'gradium':
+        audioData = await synthGradium(logger, {
+          credentials, options, stats, voice, key, text, renderForCaching, disableTtsStreaming,
+          disableTtsCache});
+        break;
+      case 'nineninesix':
+        audioData = await synthNineninesix(logger, {
+          credentials, stats, language, voice, key, text, renderForCaching, disableTtsStreaming,
+          disableTtsCache});
+        break;
       case 'inworld':
         audioData = await synthInworld(logger, {
           credentials, options, stats, language, voice, key, text, renderForCaching, disableTtsStreaming,
@@ -383,6 +401,32 @@ const synthPolly = async(createHash, retrieveHash, logger,
   }
 };
 
+/* google AudioConfig settings we support, as [google camelCase name, freeswitch param name] */
+const GOOGLE_AUDIO_SETTINGS = [
+  ['speakingRate', 'speaking_rate'],
+  ['pitch', 'pitch'],
+  ['volumeGainDb', 'volume_gain_db']
+];
+
+/**
+ * Extract google AudioConfig settings from the synthesizer options.  They may be supplied
+ * nested under an audioConfig property (mirroring google's AudioConfig object) or flat at
+ * the top level, and either google's camelCase or snake_case names are accepted.
+ * @see https://cloud.google.com/text-to-speech/docs/reference/rest/v1/text/synthesize#AudioConfig
+ * @returns object keyed by google's camelCase names, holding only valid numeric settings
+ */
+const googleAudioConfig = (options) => {
+  const provided = {...options, ...(options?.audioConfig || {})};
+  const audioConfig = {};
+  for (const [name, snakeName] of GOOGLE_AUDIO_SETTINGS) {
+    const value = provided[name] ?? provided[snakeName];
+    /* note: 0 is meaningful for pitch and volumeGainDb, so check for absence explicitly */
+    if (value === undefined || value === null || value === '') continue;
+    const num = Number(value);
+    if (Number.isFinite(num)) audioConfig[name] = num;
+  }
+  return audioConfig;
+};
 
 const synthGoogle = async(logger, {
   credentials, stats, language, voice, gender, key, text, model, options, instructions,
@@ -418,6 +462,15 @@ const synthGoogle = async(logger, {
     // comma is used to separate parameters in freeswitch tts module
     const prompt = options?.prompt || instructions;
     if (prompt) params += `,prompt=${prompt.replace(/\n/g, ' ').replace(/,/g, ';')}`;
+    /**
+     * AudioConfig settings.  Note google only honors these in some api modes:
+     * tts applies all of them, live (HD voices) applies speakingRate only,
+     * and gemini ignores them entirely (use prompt instead for style control).
+     */
+    const audioSettings = googleAudioConfig(options);
+    for (const [name, snakeName] of GOOGLE_AUDIO_SETTINGS) {
+      if (name in audioSettings) params += `,${snakeName}=${audioSettings[name]}`;
+    }
     params += '}';
 
     return {
@@ -486,6 +539,9 @@ const synthGoogle = async(logger, {
     sampleRate = 8000;
   }
 
+  /* gemini voices do not support the AudioConfig settings; they use prompt for style control */
+  if (!isGemini) Object.assign(audioConfig, googleAudioConfig(options));
+
   const opts = { input, voice: voiceParams, audioConfig };
 
   try {
@@ -1385,6 +1441,118 @@ const synthCartesia = async(logger, {
 
 };
 
+/* gradium.ai — json websocket for streaming, and a POST endpoint for the cache
+   render. only_audio:true + pcm_8000 returns bare little-endian 16-bit samples,
+   which is exactly the r8 container, so we avoid gradium's streaming wav header
+   (it carries 0xffffffff as the RIFF size, since length is unknown up front).
+*/
+const synthGradium = async(logger, {
+  credentials, options, stats, voice, key, text, renderForCaching, disableTtsStreaming, disableTtsCache
+}) => {
+  const {api_key, model_id} = credentials;
+  const {json_config, pronunciation_id} = options || {};
+
+  /* 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=gradium';
+    params += `,voice=${voice}`;
+    params += `,write_cache_file=${disableTtsCache ? 0 : 1}`;
+    if (model_id) params += `,model_id=${model_id}`;
+    if (pronunciation_id) params += `,pronunciation_id=${pronunciation_id}`;
+    params += '}';
+
+    return {
+      filePath: `say:${params}${text.replace(/\n/g, ' ').replace(/\r/g, ' ')}`,
+      servedFromCache: false,
+      rtt: 0
+    };
+  }
+
+  try {
+    const sampleRate = 8000;
+    const post = bent('https://api.gradium.ai', 'POST', 'buffer', {
+      'x-api-key': api_key,
+      'Content-Type': 'application/json'
+    });
+    const audioContent = await post('/api/post/speech/tts', {
+      text,
+      voice_id: voice,
+      model_name: model_id || 'default',
+      output_format: `pcm_${sampleRate}`,
+      only_audio: true,
+      ...(json_config && {json_config}),
+      ...(pronunciation_id && {pronunciation_id})
+    });
+    return {
+      audioContent,
+      extension: 'r8',
+      sampleRate
+    };
+  } catch (err) {
+    logger.info({err}, 'synth gradium returned error');
+    stats.increment('tts.count', ['vendor:gradium', '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. */
+const synthNineninesix = async(logger, {
+  credentials, stats, voice, language, key, text, renderForCaching, disableTtsStreaming, disableTtsCache
+}) => {
+  const {api_key, model_id} = credentials;
+
+  /* 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 += `,model_id=${model_id}`;
+    params += ',vendor=nineninesix';
+    params += `,voice=${voice}`;
+    params += `,write_cache_file=${disableTtsCache ? 0 : 1}`;
+    if (language) params += `,language=${language}`;
+    params += '}';
+
+    return {
+      filePath: `say:${params}${text.replace(/\n/g, ' ').replace(/\r/g, ' ')}`,
+      servedFromCache: false,
+      rtt: 0
+    };
+  }
+
+  try {
+    const sampleRate = 8000;
+    const post = bent('https://api.nineninesix.ai', 'POST', 'buffer', {
+      'Authorization': `Bearer ${api_key}`,
+      'Content-Type': 'application/json'
+    });
+    const audioContent = await post('/tts/bytes', {
+      model_id,
+      transcript: text,
+      voice: {mode: 'id', id: voice},
+      ...(language && {language}),
+      output_format: {
+        container: 'wav',
+        encoding: 'pcm_s16le',
+        sample_rate: sampleRate
+      }
+    });
+    return {
+      audioContent,
+      extension: 'wav',
+      sampleRate
+    };
+  } catch (err) {
+    logger.info({err}, 'synth nineninesix returned error');
+    stats.increment('tts.count', ['vendor:nineninesix', 'accepted:no']);
+    throw err;
+  }
+};
+
 const synthResemble = async(logger, {
   credentials, options, stats, voice, key, text, renderForCaching, disableTtsStreaming, disableTtsCache
 }) => {

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@jambonz/speech-utils",
-  "version": "1.0.9",
+  "version": "1.0.12",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "@jambonz/speech-utils",
-      "version": "1.0.9",
+      "version": "1.0.12",
       "license": "MIT",
       "dependencies": {
         "23": "^0.0.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jambonz/speech-utils",
-  "version": "1.0.9",
+  "version": "1.0.12",
   "description": "TTS-related speech utilities for jambonz",
   "main": "index.js",
   "author": "Dave Horton",

test/synth.js

@@ -442,6 +442,95 @@ test('Google TTS streaming tests (!JAMBONES_DISABLE_TTS_STREAMING)', async(t) =>
     });
     t.ok(result.filePath.includes('api_mode=tts'), 'options.apiMode=tts overrides HD voice default');
 
+    /* AudioConfig settings (speakingRate, pitch, volumeGainDb) */
+    const googleCreds = {
+      credentials: {
+        client_email: creds.client_email,
+        private_key: creds.private_key,
+      },
+    };
+
+    // Test 9: AudioConfig nested under options.audioConfig, as in google's API docs
+    result = await synthAudio(stats, {
+      vendor: 'google',
+      credentials: googleCreds,
+      language: 'en-US',
+      voice: 'en-US-Wavenet-D',
+      text: 'Testing nested audioConfig settings.',
+      options: { audioConfig: { speakingRate: 1.4, pitch: -2.5, volumeGainDb: 6 } },
+      disableTtsCache: true
+    });
+    t.ok(result.filePath.includes(',speaking_rate=1.4'), 'nested audioConfig sets speaking_rate');
+    t.ok(result.filePath.includes(',pitch=-2.5'), 'nested audioConfig sets pitch');
+    t.ok(result.filePath.includes(',volume_gain_db=6'), 'nested audioConfig sets volume_gain_db');
+
+    // Test 10: AudioConfig flat at the top level of options, in camelCase or snake_case
+    result = await synthAudio(stats, {
+      vendor: 'google',
+      credentials: googleCreds,
+      language: 'en-US',
+      voice: 'en-US-Wavenet-D',
+      text: 'Testing flat audioConfig settings.',
+      options: { speaking_rate: '0.8', volumeGainDb: 3 },
+      disableTtsCache: true
+    });
+    t.ok(result.filePath.includes(',speaking_rate=0.8'), 'flat snake_case speaking_rate is honored');
+    t.ok(result.filePath.includes(',volume_gain_db=3'), 'flat camelCase volumeGainDb is honored');
+    t.ok(!result.filePath.includes(',pitch='), 'unspecified audioConfig setting is omitted');
+
+    // Test 11: zero is a meaningful value for pitch and volumeGainDb, not an absent one
+    result = await synthAudio(stats, {
+      vendor: 'google',
+      credentials: googleCreds,
+      language: 'en-US',
+      voice: 'en-US-Wavenet-D',
+      text: 'Testing zero audioConfig settings.',
+      options: { audioConfig: { pitch: 0, volumeGainDb: 0 } },
+      disableTtsCache: true
+    });
+    t.ok(result.filePath.includes(',pitch=0'), 'pitch=0 is passed through rather than dropped');
+    t.ok(result.filePath.includes(',volume_gain_db=0'), 'volume_gain_db=0 is passed through rather than dropped');
+
+    // Test 12: non-numeric values are ignored, so they cannot corrupt the freeswitch param string
+    result = await synthAudio(stats, {
+      vendor: 'google',
+      credentials: googleCreds,
+      language: 'en-US',
+      voice: 'en-US-Wavenet-D',
+      text: 'Testing invalid audioConfig settings.',
+      options: { audioConfig: { speakingRate: 'fast,evil=1', pitch: null, volumeGainDb: '' } },
+      disableTtsCache: true
+    });
+    t.ok(!result.filePath.includes('speaking_rate'), 'non-numeric speakingRate is ignored');
+    t.ok(!result.filePath.includes('evil=1'), 'non-numeric value cannot inject extra params');
+    t.ok(!result.filePath.includes('pitch='), 'null pitch is ignored');
+    t.ok(!result.filePath.includes('volume_gain_db'), 'empty volumeGainDb is ignored');
+
+    // Test 13: no audioConfig supplied leaves the param string untouched
+    result = await synthAudio(stats, {
+      vendor: 'google',
+      credentials: googleCreds,
+      language: 'en-US',
+      voice: 'en-US-Wavenet-D',
+      text: 'Testing absent audioConfig settings.',
+      disableTtsCache: true
+    });
+    t.ok(!/speaking_rate|pitch=|volume_gain_db/.test(result.filePath),
+      'no audioConfig params are added when none are supplied');
+
+    // Test 14: HD voice (api_mode=live) also carries speaking_rate, the one setting google streams support
+    result = await synthAudio(stats, {
+      vendor: 'google',
+      credentials: googleCreds,
+      language: 'en-US',
+      voice: 'en-US-Chirp3-HD-Charon',
+      text: 'Testing audioConfig on an HD voice.',
+      options: { audioConfig: { speakingRate: 1.25 } },
+      disableTtsCache: true
+    });
+    t.ok(result.filePath.includes('api_mode=live'), 'HD voice with audioConfig still uses api_mode=live');
+    t.ok(result.filePath.includes(',speaking_rate=1.25'), 'HD voice streaming path carries speaking_rate');
+
   } catch (err) {
     console.error(err);
     t.end(err);
@@ -526,6 +615,42 @@ test('Google TTS non-streaming tests (JAMBONES_DISABLE_TTS_STREAMING=true)', asy
     t.ok(!result.filePath.startsWith('say:'), 'Gemini TTS does NOT return streaming say: path when disabled');
     t.ok(result.filePath.endsWith('.mp3'), 'Gemini TTS returns mp3 file path');
 
+    const googleCreds = {
+      credentials: {
+        client_email: creds.client_email,
+        private_key: creds.private_key,
+      },
+    };
+
+    /**
+     * Test 4: AudioConfig settings are accepted by the synthesize API.
+     * Google rejects out-of-range values with a 400, so a successful render also confirms
+     * the settings reached the request rather than being silently dropped.
+     */
+    result = await synthAudio(stats, {
+      vendor: 'google',
+      credentials: googleCreds,
+      language: 'en-US',
+      voice: 'en-US-Wavenet-D',
+      text: 'This is a test of audioConfig with streaming disabled.',
+      options: { audioConfig: { speakingRate: 1.4, pitch: -2.5, volumeGainDb: 6 } },
+      disableTtsCache: true
+    });
+    t.ok(result.filePath.endsWith('.mp3'), 'standard voice renders mp3 with audioConfig settings applied');
+
+    /* Test 5: gemini voices ignore the AudioConfig settings rather than failing on them */
+    result = await synthAudio(stats, {
+      vendor: 'google',
+      credentials: googleCreds,
+      language: 'en-US',
+      voice: 'Kore',
+      model: geminiModel,
+      text: 'This is a test of audioConfig on Gemini TTS.',
+      options: { audioConfig: { speakingRate: 1.4, pitch: -2.5, volumeGainDb: 6 } },
+      disableTtsCache: true
+    });
+    t.ok(result.filePath.endsWith('.mp3'), 'gemini voice renders mp3 with audioConfig settings skipped');
+
   } catch (err) {
     console.error(err);
     t.end(err);
@@ -933,6 +1058,65 @@ test('Cartesia speech synth tests', async(t) => {
   client.quit();
 });
 
+test('gradium speech synth tests', async(t) => {
+  const fn = require('..');
+  const {synthAudio, client} = fn(opts, logger);
+
+  if (!process.env.GRADIUM_API_KEY) {
+    t.pass('skipping gradium speech synth tests since GRADIUM_API_KEY is not provided');
+    return t.end();
+  }
+  const text = 'Hi there and welcome to jambones! ' + Date.now();
+  try {
+    const opts = await synthAudio(stats, {
+      vendor: 'gradium',
+      credentials: {
+        api_key: process.env.GRADIUM_API_KEY,
+        model_id: 'default'
+      },
+      voice: 'YTpq7expH9539ERJ',
+      text,
+      renderForCaching: true
+    });
+    t.ok(!opts.servedFromCache, `successfully synthed gradium audio to ${opts.filePath}`);
+
+  } catch (err) {
+    console.error(JSON.stringify(err));
+    t.end(err);
+  }
+  client.quit();
+});
+
+test('nineninesix speech synth tests', async(t) => {
+  const fn = require('..');
+  const {synthAudio, client} = fn(opts, logger);
+
+  if (!process.env.NINENINESIX_API_KEY) {
+    t.pass('skipping nineninesix speech synth tests since NINENINESIX_API_KEY is not provided');
+    return t.end();
+  }
+  const text = 'Hi there and welcome to jambones! ' + Date.now();
+  try {
+    const opts = await synthAudio(stats, {
+      vendor: 'nineninesix',
+      credentials: {
+        api_key: process.env.NINENINESIX_API_KEY,
+        model_id: 'gepard-1.0'
+      },
+      language: 'en',
+      voice: '3ad7a827-7fd1-4954-bf35-47d4cc33d9ed',
+      text,
+      renderForCaching: true
+    });
+    t.ok(!opts.servedFromCache, `successfully synthed nineninesix audio to ${opts.filePath}`);
+
+  } catch (err) {
+    console.error(JSON.stringify(err));
+    t.end(err);
+  }
+  client.quit();
+});
+
 test('inworld speech synth', async(t) => {
   const fn = require('..');
   const {synthAudio, client} = fn(opts, logger);