@fonoster/voice 0.25.0 → 0.26.0

package/README.md

@@ -33,6 +33,37 @@ A Voice Application is a server that controls a call's flow. A Voice Application
 - `Record` - It records the voice of the calling party and saves the audio on the Storage sub-system
 - `Mute` - It tells the channel to stop sending media, effectively muting the channel
 - `Unmute` - It tells the channel to allow media flow
+- `SetAudioFilters` - Filters the caller's audio in the Media Server before it reaches speech recognition and your media stream
+
+### Audio filters
+
+Background voices — a television, a radio, someone else in the room — get transcribed too, and
+your application ends up answering them. Ask the Media Server to filter the caller's audio before
+it reaches speech recognition and your media stream:
+
+```typescript
+const { aiCoustics } = require("@fonoster/voice");
+
+new VoiceServer().listen(async (req: VoiceRequest, voice: VoiceResponse) => {
+  // Set filters before answering; they apply for the rest of the session
+  await voice.setAudioFilters([aiCoustics({ enhancementLevel: 0.8 })]);
+
+  await voice.answer();
+  // ...
+});
+```
+
+Notes:
+
+- The filter runs in the Media Server, which needs the optional
+  `@ai-coustics/aic-sdk` package and an `AIC_SDK_LICENSE` key
+  ([developers.ai-coustics.com](https://developers.ai-coustics.com)). Credentials never leave the
+  Media Server, so your application never handles them.
+- `enhancementLevel` goes from 0 to 1; higher values also suppress competing speech.
+- If the filter cannot be applied, `setAudioFilters` throws and **the call continues with
+  unfiltered audio**. Catch it if a failure should not interrupt your flow.
+- Filtering adds about 30 ms of delay to the audio your application hears.
+- Sending a new list replaces the previous one, and an empty list removes all filters.
 
 Voice Application Example:
 

package/dist/VoiceResponse.d.ts

@@ -16,7 +16,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { DialOptions, GatherOptions, GatherResponse, MuteOptions, PlaybackControlAction, PlayOptions, PlayResponse, RecordOptions, RecordResponse, SayOptions, StreamEvent, StreamGatherOptions, StreamOptions, VerbResponse, VoiceRequest, VoiceSessionStreamServer } from "@fonoster/common";
+import { AudioFilterConfig, DialOptions, GatherOptions, GatherResponse, MuteOptions, PlaybackControlAction, PlayOptions, PlayResponse, RecordOptions, RecordResponse, SayOptions, StreamEvent, StreamGatherOptions, StreamOptions, VerbResponse, VoiceRequest, VoiceSessionStreamServer } from "@fonoster/common";
 import { DialStatusStream, Stream, StreamGatherStream } from "./verbs";
 /**
  * @classdesc Use the VoiceResponse object, to construct advance Interactive
@@ -235,6 +235,27 @@ declare class VoiceResponse {
      * }
      */
     sgather(options: StreamGatherOptions): Promise<StreamGatherStream>;
+    /**
+     * Sets the audio filters for this session. Filters run in the Media Server,
+     * on the caller's audio, before it reaches speech recognition and the
+     * application's media stream. Call it before answering.
+     *
+     * Sending a new list replaces the previous one; an empty list removes all
+     * filters. If a filter cannot be created — an unknown name, invalid options,
+     * a missing SDK or license — the verb fails and the call continues with
+     * unfiltered audio.
+     *
+     * @param {AudioFilterConfig[]} filters - The filters to run, in order
+     * @return {Promise<void>}
+     * @see aiCoustics
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.setAudioFilters([aiCoustics({ enhancementLevel: 0.8 })]);
+     *   await response.answer();
+     * }
+     */
+    setAudioFilters(filters: AudioFilterConfig[]): Promise<void>;
     /**
      * Mutes a call.
      *

package/dist/VoiceResponse.js

@@ -355,6 +355,46 @@ class VoiceResponse {
             return stream;
         });
     }
+    /**
+     * Sets the audio filters for this session. Filters run in the Media Server,
+     * on the caller's audio, before it reaches speech recognition and the
+     * application's media stream. Call it before answering.
+     *
+     * Sending a new list replaces the previous one; an empty list removes all
+     * filters. If a filter cannot be created — an unknown name, invalid options,
+     * a missing SDK or license — the verb fails and the call continues with
+     * unfiltered audio.
+     *
+     * @param {AudioFilterConfig[]} filters - The filters to run, in order
+     * @return {Promise<void>}
+     * @see aiCoustics
+     * @example
+     *
+     * async function handler (request, response) {
+     *   await response.setAudioFilters([aiCoustics({ enhancementLevel: 0.8 })]);
+     *   await response.answer();
+     * }
+     */
+    setAudioFilters(filters) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const result = yield new verbs_1.SetAudioFilters(this.request, this.voice).run({
+                mediaSessionRef: this.request.mediaSessionRef,
+                filters: filters.map((filter) => {
+                    var _a;
+                    return ({
+                        name: filter.name,
+                        options: pb_util_1.struct.encode(((_a = filter.options) !== null && _a !== void 0 ? _a : {}))
+                    });
+                })
+            });
+            // The Media Server applies what it can and keeps the call alive; anything
+            // it refused comes back here so the application can log or react to it.
+            if ((_a = result.setAudioFiltersResponse) === null || _a === void 0 ? void 0 : _a.error) {
+                throw new Error(result.setAudioFiltersResponse.error);
+            }
+        });
+    }
     /**
      * Mutes a call.
      *

package/dist/filters.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { AudioFilterConfig } from "@fonoster/common";
+/**
+ * Options for the ai-coustics filter. Tuning only: the license key is read
+ * from the Media Server's environment and never travels with the session.
+ */
+type AiCousticsOptions = {
+    /** Model to load. Defaults to Quail Voice Focus at 16 kHz. */
+    model?: string;
+    /** 0 to 1. Higher values also suppress competing speech. Defaults to 1. */
+    enhancementLevel?: number;
+    /** Keeps the processing delay but stops enhancing. Useful for A/B tests. */
+    bypass?: boolean;
+};
+/**
+ * ai-coustics speech enhancement: keeps the primary speaker and suppresses
+ * noise and competing voices.
+ *
+ * @param {AiCousticsOptions} options - Tuning options for the filter
+ * @return {AudioFilterConfig} A filter to pass to `setAudioFilters`
+ * @example
+ *
+ * await voice.setAudioFilters([aiCoustics({ enhancementLevel: 0.8 })]);
+ * await voice.answer();
+ */
+declare function aiCoustics(options?: AiCousticsOptions): AudioFilterConfig;
+export { aiCoustics, AiCousticsOptions };

package/dist/filters.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aiCoustics = aiCoustics;
+/**
+ * ai-coustics speech enhancement: keeps the primary speaker and suppresses
+ * noise and competing voices.
+ *
+ * @param {AiCousticsOptions} options - Tuning options for the filter
+ * @return {AudioFilterConfig} A filter to pass to `setAudioFilters`
+ * @example
+ *
+ * await voice.setAudioFilters([aiCoustics({ enhancementLevel: 0.8 })]);
+ * await voice.answer();
+ */
+function aiCoustics(options = {}) {
+    return { name: "aiCoustics", options };
+}

package/dist/index.d.ts

@@ -20,5 +20,6 @@ import { AzureVoice, AzureVoiceDetails, GatherSource, GoogleVoice, GoogleVoiceDe
 import VoiceServer from "./VoiceServer";
 export default VoiceServer;
 export * from "./VoiceResponse";
+export * from "./filters";
 export * from "./types";
 export { AzureVoice, AzureVoiceDetails, GatherSource, GoogleVoice, GoogleVoiceDetails, StreamGatherSource };

package/dist/index.js

@@ -46,4 +46,5 @@ Object.defineProperty(exports, "StreamGatherSource", { enumerable: true, get: fu
 const VoiceServer_1 = __importDefault(require("./VoiceServer"));
 exports.default = VoiceServer_1.default;
 __exportStar(require("./VoiceResponse"), exports);
+__exportStar(require("./filters"), exports);
 __exportStar(require("./types"), exports);

package/dist/verbs/SetAudioFilters.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { SetAudioFiltersRequest } from "@fonoster/common";
+import { z } from "zod";
+import { Verb } from "./Verb";
+declare class SetAudioFilters extends Verb<SetAudioFiltersRequest> {
+    getValidationSchema(): z.Schema;
+}
+export { SetAudioFilters };

package/dist/verbs/SetAudioFilters.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SetAudioFilters = void 0;
+const zod_1 = require("zod");
+const Verb_1 = require("./Verb");
+class SetAudioFilters extends Verb_1.Verb {
+    getValidationSchema() {
+        return zod_1.z.object({
+            filters: zod_1.z.array(zod_1.z.object({
+                name: zod_1.z.string().min(1, { message: "A filter name is required" }),
+                options: zod_1.z.record(zod_1.z.unknown()).optional()
+            }))
+        });
+    }
+}
+exports.SetAudioFilters = SetAudioFilters;

package/dist/verbs/index.d.ts

@@ -32,3 +32,4 @@ export * from "./Unmute";
 export * from "./Verb";
 export * from "./validateRequest";
 export * from "./StopSay";
+export * from "./SetAudioFilters";

package/dist/verbs/index.js

@@ -48,3 +48,4 @@ __exportStar(require("./Unmute"), exports);
 __exportStar(require("./Verb"), exports);
 __exportStar(require("./validateRequest"), exports);
 __exportStar(require("./StopSay"), exports);
+__exportStar(require("./SetAudioFilters"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fonoster/voice",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Voice Server for Fonoster",
   "author": "Pedro Sanders <psanders@fonoster.com>",
   "homepage": "https://github.com/fonoster/fonoster#readme",
@@ -22,9 +22,9 @@
     "fonoster": "./dist/index.js"
   },
   "dependencies": {
-    "@fonoster/common": "^0.25.0",
-    "@fonoster/identity": "^0.25.0",
-    "@fonoster/logger": "^0.25.0",
+    "@fonoster/common": "^0.26.0",
+    "@fonoster/identity": "^0.26.0",
+    "@fonoster/logger": "^0.26.0",
     "@grpc/grpc-js": "~1.10.6",
     "deepmerge": "^4.3.1",
     "grpc-health-check": "^2.0.2",
@@ -45,5 +45,5 @@
   "bugs": {
     "url": "https://github.com/fonoster/fonoster/issues"
   },
-  "gitHead": "3f63a173d31c0dbf2391b1eff907c8880e60614d"
+  "gitHead": "d14f414d791a33f92e8c4225f7e462abc440a142"
 }