perf(rime): stream sentence batches and reuse WebSocket connections

.github/workflows/test.yml

@@ -16,6 +16,7 @@ on:
       - 'agents/**'
       - 'package.json'
       - 'plugins/test/**'
+      - 'plugins/rime/**'
       - 'pnpm-lock.yaml'
       - 'pnpm-workspace.yaml'
       - 'turbo.json'
@@ -48,6 +49,8 @@ jobs:
         run: pnpm build
       - name: Test agents
         run: pnpm test agents --silent
+      - name: Test Rime plugin
+        run: pnpm test plugins/rime --silent
       - name: Test LiveKit inference
         env:
           LIVEKIT_INFERENCE_TESTS: '1'

plugins/rime/README.md

@@ -3,6 +3,7 @@ SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 
 SPDX-License-Identifier: Apache-2.0
 -->
+
 # Rime plugin for LiveKit Agents
 
 The Agents Framework is designed for building realtime, programmable
@@ -13,4 +14,38 @@ This package contains the Rime plugin, which provides high-quality text-to-speec
 [documentation](https://docs.livekit.io/agents/overview/) for information on how to use it,
 or browse the [API reference](https://docs.livekit.io/agents-js/modules/plugins_agents_plugin_rime.html).
 See the [repository](https://github.com/livekit/agents-js) for more information
-about the framework as a whole.
+about the framework as a whole.
+
+## WebSocket sentence streaming and reuse
+
+For `segment: 'never'`, sentence flushing and connection reuse are opt-in:
+
+```ts
+const speech = new rime.TTS({
+  modelId: 'coda',
+  speaker: 'lyra',
+  useWebsocket: true,
+  segment: 'never',
+  flushSentences: true,
+  reuseWebsocket: true,
+});
+```
+
+`flushSentences` sends each sentence emitted by the configured tokenizer and
+waits for that synthesis batch's `done` event before sending the next sentence.
+This prevents overlapping flushes from being combined by Rime. Explicit SDK
+`stream.flush()` calls still finish separate audio segments and metrics;
+whitespace-only segments are ignored. The
+tokenizer retains control over when text is ready; this option does not bypass
+its buffering or alter its sentence boundaries.
+
+`reuseWebsocket` retains at most one successfully completed connection per TTS
+instance for up to 30 idle seconds. Simultaneous streams use separate sockets.
+Interrupted or failed streams discard their connections; voice, language, or
+other connection-option changes prevent reuse of the old connection. Call
+`await speech.close()` during application shutdown to release active and idle
+connections and cancel pending connections.
+
+Both options default to `false`; existing HTTP and WebSocket behavior is unchanged
+unless enabled. See the [Rime WebSocket segmentation contract](https://docs.rime.ai/docs/websockets-segment)
+for provider flush and completion semantics.

plugins/rime/etc/agents-plugin-rime.api.md

@@ -32,8 +32,11 @@ export type DefaultLanguages = 'eng' | 'spa' | 'fra' | 'ger';
 // @public (undocumented)
 export class SynthesizeStream extends tts.SynthesizeStream {
     constructor(tts: TTS, opts: TTSOptions, connOptions?: APIConnectOptions);
+    flush(): void;
     // (undocumented)
     label: string;
+    // @deprecated
+    pushText(text: string): void;
     // (undocumented)
     protected run(): Promise<void>;
 }
@@ -43,6 +46,7 @@ export class SynthesizeStream extends tts.SynthesizeStream {
 // @public (undocumented)
 export class TTS extends tts.TTS {
     constructor(opts?: Partial<TTSOptions>);
+    close(): Promise<void>;
     // (undocumented)
     label: string;
     // (undocumented)
@@ -60,7 +64,7 @@ export class TTS extends tts.TTS {
 // Warning: (ae-missing-release-tag) "TTSModels" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public
-export type TTSModels = 'arcana' | 'coda' | 'mistv2' | 'mistv3';
+export type TTSModels = 'coda' | 'mistv2' | 'mistv3';
 
 // Warning: (ae-missing-release-tag) "TTSOptions" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -71,6 +75,7 @@ export interface TTSOptions {
     apiKey?: string;
     // (undocumented)
     baseURL?: string;
+    flushSentences?: boolean;
     // (undocumented)
     inlineSpeedAlpha?: string;
     // (undocumented)
@@ -89,6 +94,7 @@ export interface TTSOptions {
     reduceLatency?: boolean;
     // (undocumented)
     repetition_penalty?: number;
+    reuseWebsocket?: boolean;
     // (undocumented)
     samplingRate?: number;
     // (undocumented)