Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Changelog

## [4.43.2]

- `StreamingTranscriber.updateConfiguration()` takes `mode`, `max_turn_duration` and `continuous_partials`, which the streaming API accepts mid-stream, and takes each field by its camelCase connection-param name (`maxTurnSilence`, `keytermsPrompt`, ...) as well as its snake_case name, sending it as the snake_case field. The API ignored camelCase names before, so `updateConfiguration({ maxTurnSilence: 1500 })` from plain JavaScript changed nothing. When both names of a field are given with different values, the snake_case value is sent, with a warning. Unrecognized keys are still sent, with a warning. `format_turns` and `filter_profanity` are deprecated on `StreamingUpdateConfiguration` and warn when sent, since the API does not apply them mid-stream. New type `StreamingUpdateConfigurationParams`

## [4.43.1]

- `client.tts.synthesize()` and `client.tts.stream()` send the camelCase names `voiceId`, `modelId`, `sampleRate`, `bitRate` and `extendBiometricConsent`, which plain JavaScript can pass, as their snake_case request fields (`voice_id`, ...) and warn once. The API ignored them before, so such a request got the default voice, model or sample rate. These values now reach the API, so a value it refuses (a `sampleRate` outside the supported set, `bitRate` without the `mp3` encoding, `extendBiometricConsent` on a voice the account does not own) fails with the same `TextToSpeechError` as its snake_case spelling, where before the request used the default. When a request gives both names of a field with different values, the snake_case value is sent, with a warning once. A `TextToSpeechSession` warns once on the snake_case names it ignores (`voice_id`, `model_id`, `sample_rate`, `extend_biometric_consent`, `word_boundaries`, `inactivity_timeout`)
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "assemblyai",
"version": "4.43.1",
"version": "4.43.2",
"description": "The AssemblyAI JavaScript SDK provides an easy-to-use interface for interacting with the AssemblyAI API, which supports async and real-time transcription and text-to-speech.",
"engines": {
"node": ">=18"
Expand Down
124 changes: 121 additions & 3 deletions src/services/streaming/service.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ import {
LLMGatewayResponseEvent,
SpeakerRevisionEvent,
StreamingUpdateConfiguration,
StreamingUpdateConfigurationParams,
StreamingForceEndpoint,
StreamingKeepAlive,
WarningEvent,
Expand Down Expand Up @@ -67,6 +68,118 @@ const terminateSessionMessage = `{"type":"Terminate"}`;

const DEFAULT_CONNECT_TIMEOUT_MS = 1000;

type UpdateConfigurationField = Exclude<
keyof StreamingUpdateConfiguration,
"type"
>;

/**
* The snake_case fields of an `UpdateConfiguration` message. Typed as a
* record over `StreamingUpdateConfiguration` so adding a field to the type
* without listing it here fails to compile.
*/
const UPDATE_CONFIGURATION_FIELDS: Record<UpdateConfigurationField, true> = {
mode: true,
end_of_turn_confidence_threshold: true,
min_end_of_turn_silence_when_confident: true,
min_turn_silence: true,
max_turn_silence: true,
vad_threshold: true,
max_turn_duration: true,
format_turns: true,
session_heartbeat: true,
acknowledge_silence: true,
keyterms_prompt: true,
prompt: true,
agent_context: true,
filter_profanity: true,
interruption_delay: true,
turn_left_pad_ms: true,
continuous_partials: true,
language_codes: true,
};

/** Fields the server accepts on `UpdateConfiguration` but does not apply. */
const NOT_UPDATABLE_FIELDS: ReadonlySet<string> = new Set([
"format_turns",
"filter_profanity",
]);

function isUpdateConfigurationField(
key: string,
): key is UpdateConfigurationField {
return Object.prototype.hasOwnProperty.call(UPDATE_CONFIGURATION_FIELDS, key);
}

function camelToSnakeCase(key: string): string {
return key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
}

/**
* Resolves `updateConfiguration()` input to snake_case wire fields: camelCase
* names map to their snake_case field, the snake_case value wins when both
* names of a field are given, and unrecognized keys are sent unchanged with a
* warning.
*/
function toUpdateConfigurationFields(
config: StreamingUpdateConfigurationParams,
): Record<string, unknown> {
const fields: Record<string, unknown> = {};
const fromCamelCase = new Map<string, string>();
const unrecognized: string[] = [];

for (const [key, value] of Object.entries(config)) {
if (value === undefined || key === "type") continue;
if (isUpdateConfigurationField(key)) {
if (fromCamelCase.has(key)) {
warnCasingConflict(key, fromCamelCase.get(key)!, fields[key], value);
fromCamelCase.delete(key);
}
fields[key] = value;
continue;
}
const snake = camelToSnakeCase(key);
if (snake !== key && isUpdateConfigurationField(snake)) {
if (snake in fields) {
warnCasingConflict(snake, key, value, fields[snake]);
} else {
fields[snake] = value;
fromCamelCase.set(snake, key);
}
continue;
}
unrecognized.push(key);
fields[key] = value;
}

if (unrecognized.length > 0) {
console.warn(
`updateConfiguration: unrecognized ${unrecognized.join(", ")}; sent unchanged, and the server ignores fields it does not accept.`,
);
}
const notUpdatable = Object.keys(fields).filter((key) =>
NOT_UPDATABLE_FIELDS.has(key),
);
if (notUpdatable.length > 0) {
console.warn(
`updateConfiguration: ${notUpdatable.join(", ")} cannot be changed mid-stream; set it when creating the transcriber.`,
);
}
return fields;
}

function warnCasingConflict(
snake: string,
camel: string,
camelValue: unknown,
snakeValue: unknown,
) {
if (JSON.stringify(camelValue) === JSON.stringify(snakeValue)) return;
console.warn(
`updateConfiguration: both \`${snake}\` and \`${camel}\` are set with different values; sending \`${snake}\`.`,
);
}

/**
* How long `close()` waits for the server's `Termination` frame before giving
* up. The socket is closed either way, so this only bounds the wait. A server
Expand Down Expand Up @@ -1027,14 +1140,19 @@ Learn more at https://github.com/AssemblyAI/assemblyai-node-sdk/blob/main/docs/c

/**
* Update the streaming configuration mid-stream.
* @param config - The configuration parameters to update
* @param config - The fields to update, by their snake_case wire names or
* the camelCase names of the connection params. Unrecognized keys are sent
* unchanged, with a warning.
*/
updateConfiguration(config: Omit<StreamingUpdateConfiguration, "type">) {
updateConfiguration(config: StreamingUpdateConfigurationParams) {
const {
min_end_of_turn_silence_when_confident,
min_turn_silence,
...rest
} = config;
} = toUpdateConfigurationFields(config) as Omit<
StreamingUpdateConfiguration,
"type"
>;
if (min_end_of_turn_silence_when_confident !== undefined) {
if (min_turn_silence !== undefined) {
console.warn(
Expand Down
38 changes: 38 additions & 0 deletions src/types/streaming/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -387,6 +387,8 @@ export type StreamingTerminateSession = {

export type StreamingUpdateConfiguration = {
type: "UpdateConfiguration";
/** Switch the latency/accuracy preset mid-stream. U3Pro only. */
mode?: StreamingMode;
end_of_turn_confidence_threshold?: number;
/**
* @deprecated Use `min_turn_silence` instead. This parameter will be removed in a future release.
Expand All @@ -395,15 +397,29 @@ export type StreamingUpdateConfiguration = {
min_turn_silence?: number;
max_turn_silence?: number;
vad_threshold?: number;
/**
* Maximum turn length in milliseconds (16 000–128 000) before the server
* ends the turn.
*/
max_turn_duration?: number;
/**
* @deprecated The server does not apply `format_turns` mid-stream; set
* `formatTurns` when creating the transcriber.
*/
format_turns?: boolean;
session_heartbeat?: boolean;
acknowledge_silence?: boolean;
keyterms_prompt?: string[];
prompt?: string;
agent_context?: string;
/**
* @deprecated The server does not apply `filter_profanity` mid-stream; set
* `filterProfanity` when creating the transcriber.
*/
filter_profanity?: boolean;
interruption_delay?: number;
turn_left_pad_ms?: number;
continuous_partials?: boolean;
/**
* Steer transcription toward a set of languages mid-stream. Pass an empty
* array (`[]`) to clear steering and restore the model's default
Expand All @@ -412,6 +428,28 @@ export type StreamingUpdateConfiguration = {
language_codes?: string[];
};

type SnakeToCamelCase<S extends string> =
S extends `${infer Head}_${infer Tail}`
? `${Head}${Capitalize<SnakeToCamelCase<Tail>>}`
: S;

/**
* The fields `StreamingTranscriber.updateConfiguration()` takes. Each field
* can be given by its snake_case wire name (`max_turn_silence`) or by the
* camelCase name the transcriber's connection params use (`maxTurnSilence`);
* both are sent as the snake_case field. When both names of a field are given
* with different values, the snake_case value is sent.
*/
export type StreamingUpdateConfigurationParams = Omit<
StreamingUpdateConfiguration,
"type"
> & {
[K in Exclude<
keyof StreamingUpdateConfiguration,
"type"
> as SnakeToCamelCase<K>]?: StreamingUpdateConfiguration[K];
};

export type StreamingForceEndpoint = {
type: "ForceEndpoint";
};
Expand Down
98 changes: 98 additions & 0 deletions tests/unit/streaming.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1046,4 +1046,102 @@ describe("streaming", () => {
}),
);
});

describe("updateConfiguration field names", () => {
let warn: jest.SpyInstance;
beforeEach(() => {
warn = jest.spyOn(console, "warn").mockImplementation(() => {});
});
afterEach(() => warn.mockRestore());

it("should send mode", async () => {
rt.updateConfiguration({ mode: "balanced" });
await expect(server).toReceiveMessage(
JSON.stringify({ type: "UpdateConfiguration", mode: "balanced" }),
);
expect(warn).not.toHaveBeenCalled();
});

it("should map camelCase names to their snake_case fields", async () => {
rt.updateConfiguration({
maxTurnSilence: 1500,
endOfTurnConfidenceThreshold: 0.5,
keytermsPrompt: ["AssemblyAI"],
agentContext: "How can I help?",
languageCodes: ["en"],
continuousPartials: true,
maxTurnDuration: 30000,
});
await expect(server).toReceiveMessage(
JSON.stringify({
type: "UpdateConfiguration",
max_turn_silence: 1500,
end_of_turn_confidence_threshold: 0.5,
keyterms_prompt: ["AssemblyAI"],
agent_context: "How can I help?",
language_codes: ["en"],
continuous_partials: true,
max_turn_duration: 30000,
}),
);
expect(warn).not.toHaveBeenCalled();
});

it("should map camelCase minTurnSilence and the deprecated minEndOfTurnSilenceWhenConfident", async () => {
rt.updateConfiguration({ minTurnSilence: 300 });
await expect(server).toReceiveMessage(
JSON.stringify({ type: "UpdateConfiguration", min_turn_silence: 300 }),
);
rt.updateConfiguration({ minEndOfTurnSilenceWhenConfident: 200 });
await expect(server).toReceiveMessage(
JSON.stringify({ type: "UpdateConfiguration", min_turn_silence: 200 }),
);
});

it("should send the snake_case value when both names differ", async () => {
rt.updateConfiguration({ maxTurnSilence: 1500, max_turn_silence: 900 });
await expect(server).toReceiveMessage(
JSON.stringify({ type: "UpdateConfiguration", max_turn_silence: 900 }),
);
rt.updateConfiguration({ max_turn_silence: 900, maxTurnSilence: 1500 });
await expect(server).toReceiveMessage(
JSON.stringify({ type: "UpdateConfiguration", max_turn_silence: 900 }),
);
expect(warn).toHaveBeenCalledTimes(2);
expect(warn.mock.calls[0][0]).toContain("`max_turn_silence`");
});

it("should not warn when both names agree", async () => {
rt.updateConfiguration({ maxTurnSilence: 900, max_turn_silence: 900 });
await expect(server).toReceiveMessage(
JSON.stringify({ type: "UpdateConfiguration", max_turn_silence: 900 }),
);
expect(warn).not.toHaveBeenCalled();
});

it("should send unrecognized keys unchanged and warn", async () => {
const config = { max_turn_silence: 900, futureField: 1 };
rt.updateConfiguration(config);
await expect(server).toReceiveMessage(
JSON.stringify({
type: "UpdateConfiguration",
max_turn_silence: 900,
futureField: 1,
}),
);
expect(warn).toHaveBeenCalledTimes(1);
expect(warn.mock.calls[0][0]).toContain("unrecognized futureField");
});

it("should warn that format_turns cannot change mid-stream", async () => {
rt.updateConfiguration({ formatTurns: true });
await expect(server).toReceiveMessage(
JSON.stringify({ type: "UpdateConfiguration", format_turns: true }),
);
expect(warn).toHaveBeenCalledTimes(1);
expect(warn.mock.calls[0][0]).toContain(
"format_turns cannot be changed mid-stream",
);
});
});
});
Loading