Merge pull request #4 from HumeAI/twitchard/improve-streaming

Improve streaming

Author: twitchard

README.md

@@ -60,6 +60,7 @@ $ hume tts <text>
 --speed #0 Speaking speed multiplier (0.25-3.0, default is 1.0)
 --trailing-silence #0 Seconds of silence to add at the end (0.0-5.0, default is 0.35)
 --streaming Use streaming mode for TTS generation (default: true)
+--instant-mode Enable ultra-low latency mode for significantly faster generation (requires streaming=true, a voice, and incurs 10% higher cost)
 
 ━━━ Details ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
@@ -103,6 +104,12 @@ $ hume tts "I am speaking very slowly" -v narrator --speed 0.75
 Adding trailing silence
 $ hume tts "Wait for it..." -v narrator --trailing-silence 3.5
 
+Using instant mode for ultra-low latency
+$ hume tts "Hello world" -v narrator --instant-mode
+
+Setting instant mode in your config (always enable)
+$ hume config set tts.instantMode true
+
 ## Voice Management
 
 Save a voice from a previous generation

bun.lock

@@ -8,7 +8,7 @@
         "bun": "^1.2.2",
         "clipanion": "^4.0.0-rc.4",
         "debug": "^4.4.0",
-        "hume": "^0.10.0",
+        "hume": "^0.10.3",
         "open": "^10.1.0",
         "typanion": "^3.14.0",
       },
@@ -125,7 +125,7 @@
 
     "hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
 
-    "hume": ["hume@0.10.0", "", { "dependencies": { "form-data": "^4.0.0", "form-data-encoder": "^4.0.2", "formdata-node": "^6.0.3", "node-fetch": "^2.7.0", "qs": "^6.13.1", "readable-stream": "^4.5.2", "url-join": "4.0.1", "uuid": "9.0.1", "ws": "^8.14.2", "zod": "^3.23.8" } }, "sha512-rjarPoQylEIJ1lqWginPgyj0yCxBhZevyFdAarkQkgedmIBdLwW/jyYMHvFzzipALzt1NL5P0D3qmqXgPPgEmg=="],
+    "hume": ["hume@0.10.3", "", { "dependencies": { "form-data": "^4.0.0", "form-data-encoder": "^4.0.2", "formdata-node": "^6.0.3", "node-fetch": "^2.7.0", "qs": "^6.13.1", "readable-stream": "^4.5.2", "url-join": "4.0.1", "uuid": "9.0.1", "ws": "^8.14.2", "zod": "^3.23.8" } }, "sha512-CmTv98BXD5ZttNPyUbGarelB7yLoYQkCUJAy9IWSnn2WFoT2AeW6A9MYJ0ZtjiCwN/yVoKrTwyXvnlAva3BfZA=="],
 
     "ieee754": ["ieee754@1.2.1", "", {}, "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA=="],
 

package.json

@@ -26,7 +26,7 @@
     "bun": "^1.2.2",
     "clipanion": "^4.0.0-rc.4",
     "debug": "^4.4.0",
-    "hume": "^0.10.0",
+    "hume": "^0.10.3",
     "open": "^10.1.0",
     "typanion": "^3.14.0"
   },

src/common.ts

@@ -121,8 +121,6 @@ export const getSettings = async (
 };
 
 export const getHumeClient = (opts: { apiKey: string; baseUrl?: string }) => {
-  const environment = opts.baseUrl || 'https://test-api.hume.ai';
-  debug('Creating HumeClient with environment: %s', environment);
   return new HumeClient({
     apiKey: opts.apiKey,
     environment: opts.baseUrl ?? 'https://api.hume.ai',

src/config.ts

@@ -33,6 +33,7 @@ export type ConfigData = {
     speed?: number;
     trailingSilence?: number;
     streaming?: boolean;
+    instantMode?: boolean;
   };
   json?: boolean;
   pretty?: boolean;
@@ -54,6 +55,7 @@ export const configValidators = {
   'tts.speed': t.cascade(t.isNumber(), t.isInInclusiveRange(0.25, 3.0)),
   'tts.trailingSilence': t.cascade(t.isNumber(), t.isInInclusiveRange(0.0, 5.0)),
   'tts.streaming': t.isBoolean(),
+  'tts.instantMode': t.isBoolean(),
   json: t.isBoolean(),
   pretty: t.isBoolean(),
   apiKey: t.isString(),

src/e2e.test.ts

@@ -523,6 +523,9 @@ describe('CLI End-to-End Tests', () => {
       generation_id: generationId,
       audio: Buffer.from(`audio-data-${generationId}-${id}`).toString('base64'),
       utterance_index: partial.utteranceIndex ?? 0,
+      // Add the missing properties required by the RawSnippetAudioChunk type
+      snippet_id: id,
+      text: `Sample text for ${id}`,
     };
   };
 

src/index.ts

@@ -24,6 +24,8 @@ const usageDescriptions = {
   'tts.speed': 'Speaking speed multiplier (0.25-3.0, default is 1.0)',
   'tts.trailingSilence': 'Seconds of silence to add at the end (0.0-5.0, default is 0.35)',
   'tts.streaming': 'Use streaming mode for TTS generation (default: true)',
+  'tts.instantMode':
+    'Enable ultra-low latency mode for significantly faster generation (requires streaming=true, a voice, and incurs 10% higher cost)',
   apiKey: 'Override the default API key',
   json: 'Output in JSON format',
   pretty: 'Output in human-readable format',
@@ -348,6 +350,8 @@ const ttsExamples: Usage['examples'] = [
   ],
   ['Adjusting speech speed', '$0 tts "I am speaking very slowly" -v narrator --speed 0.75'],
   ['Adding trailing silence', '$0 tts "Wait for it..." -v narrator --trailing-silence 3.5'],
+  ['Using instant mode for ultra-low latency', '$0 tts "Hello world" -v narrator --instant-mode'],
+  ['Setting instant mode in your config', 'hume config set tts.instantMode true'],
 ];
 class TtsCommand extends Command {
   static paths = [['tts']];
@@ -446,6 +450,10 @@ class TtsCommand extends Command {
     description: usageDescriptions['tts.streaming'],
   });
 
+  instantMode = Option.Boolean('--instant-mode', {
+    description: usageDescriptions['tts.instantMode'],
+  });
+
   async execute() {
     const tts = new Tts();
     await tts.synthesize(this);

src/play_audio.ts

@@ -0,0 +1,130 @@
+import { debug } from './common';
+
+type Command = {
+  cmd: string;
+  argsWithPath: (path: string) => string[];
+  argsWithStdin: string[] | null;
+};
+
+let defaultAudioPlayer: Command | null | undefined = undefined;
+const findDefaultAudioPlayer = (): Command | null => {
+  if (defaultAudioPlayer === undefined) {
+    defaultAudioPlayer = findDefaultAudioPlayer_();
+  }
+  return defaultAudioPlayer;
+};
+const findDefaultAudioPlayer_ = (): Command | null => {
+  const isWindows = process.platform === 'win32';
+
+  const atEnd =
+    (...arr: string[]) =>
+    (path: string) => [...arr, path];
+
+  // Ordered by preference
+  const commonPlayers: Command[] = isWindows
+    ? [
+        {
+          cmd: 'powershell',
+          argsWithPath: (path) => ['-c', `"(New-Object Media.SoundPlayer '${path}').PlaySync()"`],
+          argsWithStdin: null,
+        },
+        {
+          cmd: 'ffplay',
+          argsWithPath: atEnd('-nodisp', '-autoexit'),
+          argsWithStdin: ['-nodisp', '-autoexit', '-i', '-'],
+        },
+        { cmd: 'mpv', argsWithPath: atEnd('--no-video'), argsWithStdin: ['--no-video', '-'] },
+        { cmd: 'mplayer', argsWithPath: atEnd(''), argsWithStdin: ['-'] },
+      ]
+    : [
+        {
+          cmd: 'ffplay',
+          argsWithPath: atEnd('-nodisp', '-autoexit'),
+          argsWithStdin: ['-nodisp', '-autoexit', '-i', '-'],
+        },
+        { cmd: 'afplay', argsWithPath: atEnd(''), argsWithStdin: null },
+        { cmd: 'mplayer', argsWithPath: atEnd(''), argsWithStdin: ['-'] },
+        { cmd: 'mpv', argsWithPath: atEnd('--no-video'), argsWithStdin: ['--no-video', '-'] },
+        { cmd: 'aplay', argsWithPath: atEnd(''), argsWithStdin: ['-'] },
+        { cmd: 'play', argsWithPath: atEnd(''), argsWithStdin: ['-'] },
+      ];
+
+  for (const player of commonPlayers) {
+    const checkCmd = isWindows ? 'where' : 'which';
+    try {
+      Bun.spawnSync([checkCmd, player.cmd]);
+      return player; // found!
+    } catch {}
+  }
+
+  return null;
+};
+
+export const playAudioFile = async (
+  path: string,
+  customCommand: string | null
+): Promise<unknown> => {
+  const command = ensureAudioPlayer(
+    customCommand ? parseCustomCommand(customCommand) : findDefaultAudioPlayer()
+  );
+  const isWindows = process.platform === 'win32';
+  const sanitizedPath = isWindows ? path.replace(/\\/g, '\\\\') : path;
+
+  return Bun.spawn([command.cmd, ...command.argsWithPath(sanitizedPath)], {
+    stdout: 'ignore',
+    stderr: 'ignore',
+  }).exited;
+};
+
+export const parseCustomCommand = (command: string): Command => {
+  const [cmd, ...args] = command.split(' ');
+  const argsWithPath = (path: string) => args.map((arg) => arg.replace('$AUDIO_FILE', path));
+  const argsWithStdin = args.some((arg) => arg.includes('$AUDIO_FILE')) ? argsWithPath('-') : args;
+
+  return {
+    cmd,
+    argsWithPath,
+    argsWithStdin,
+  };
+};
+
+const ensureAudioPlayer = (command: Command | null): Command => {
+  if (!command) {
+    throw new Error(
+      'No audio player found. Please install ffplay or specify a custom player with --play-command'
+    );
+  }
+  return command;
+};
+
+const ensureStdinSupport = (command: Command): Command & { argsWithStdin: string[] } => {
+  const { argsWithStdin } = command;
+  if (!argsWithStdin) {
+    throw new Error(
+      `The audio player does not support playing from stdin. Please specify a custom player with --play-command`
+    );
+  }
+  return { ...command, argsWithStdin };
+};
+
+export const withStdinAudioPlayer = async (
+  customCommand: string | null,
+  f: (writeAudio: (audioBuffer: Buffer) => void) => Promise<void>
+): Promise<void> => {
+  const command = ensureStdinSupport(
+    ensureAudioPlayer(customCommand ? parseCustomCommand(customCommand) : findDefaultAudioPlayer())
+  );
+
+  debug([command.cmd, command.argsWithStdin]);
+  const proc = Bun.spawn([command.cmd, ...command.argsWithStdin], {
+    stdout: 'ignore',
+    stderr: 'ignore',
+    stdin: 'pipe',
+  });
+
+  await f((audioBuffer: Buffer) => {
+    proc.stdin.write(audioBuffer);
+  });
+  proc.stdin.end();
+  await proc.exited;
+};