🤖 Merge PR DefinitelyTyped#72243 [Chrome] update tts namespaces by @erwanjugand

erwanjugand · web-flow · commit f06702b8bfae · 2025-04-11T14:59:30.000-07:00
diff --git a/types/chrome/index.d.ts b/types/chrome/index.d.ts
@@ -12367,133 +12367,143 @@ declare namespace chrome {
     // Text to Speech
     ////////////////////
     /**
-     * Use the `chrome.tts` API to play synthesized text-to-speech (TTS). See also the related ttsEngine API, which allows an extension to implement a speech engine.
+     * Use the `chrome.tts` API to play synthesized text-to-speech (TTS). See also the related {@link ttsEngine} API, which allows an extension to implement a speech engine.
      *
      * Permissions: "tts"
      */
     export namespace tts {
+        /** @since Chrome 54 */
+        export enum EventType {
+            START = "start",
+            END = "end",
+            WORD = "word",
+            SENTENCE = "sentence",
+            MARKER = "marker",
+            INTERRUPTED = "interrupted",
+            CANCELLED = "cancelled",
+            ERROR = "error",
+            PAUSE = "pause",
+            RESUME = "resume",
+        }
+
         /** An event from the TTS engine to communicate the status of an utterance. */
         export interface TtsEvent {
-            /** Optional. The index of the current character in the utterance. */
-            charIndex?: number | undefined;
-            /** Optional. The error description, if the event type is 'error'. */
-            errorMessage?: string | undefined;
+            /** The index of the current character in the utterance. For word events, the event fires at the end of one word and before the beginning of the next. The `charIndex` represents a point in the text at the beginning of the next word to be spoken. */
+            charIndex?: number;
+            /** The error description, if the event type is `error`. */
+            errorMessage?: string;
+            /**
+             * The length of the next part of the utterance. For example, in a `word` event, this is the length of the word which will be spoken next. It will be set to -1 if not set by the speech engine.
+             * @since Chrome 74
+             */
+            length?: number;
+            /** The type can be `start` as soon as speech has started, `word` when a word boundary is reached, `sentence` when a sentence boundary is reached, `marker` when an SSML mark element is reached, `end` when the end of the utterance is reached, `interrupted` when the utterance is stopped or interrupted before reaching the end, `cancelled` when it's removed from the queue before ever being synthesized, or `error` when any other error occurs. When pausing speech, a `pause` event is fired if a particular utterance is paused in the middle, and `resume` if an utterance resumes speech. Note that pause and resume events may not fire if speech is paused in-between utterances. */
+            type: `${EventType}`;
+        }
+
+        /**
+         * The speech options for the TTS engine.
+         * @since Chrome 77
+         */
+        export interface TtsOptions {
+            /** The TTS event types that you are interested in listening to. If missing, all event types may be sent. */
+            desiredEventTypes?: string[];
+            /** If true, enqueues this utterance if TTS is already in progress. If false (the default), interrupts any current speech and flushes the speech queue before speaking this new utterance. */
+            enqueue?: boolean;
+            /** The extension ID of the speech engine to use, if known. */
+            extensionId?: string;
             /**
-             * The length of the next part of the utterance.
-             * For example, in a word event, this is the length of the word which will be spoken next.
-             * It will be set to -1 if not set by the speech engine.
+             * Gender of voice for synthesized speech.
+             * @deprecated since Chrome 77. Gender is deprecated and will be ignored.
              */
-            length?: number | undefined;
+            gender?: `${VoiceGender}`;
+            /** The language to be used for synthesis, in the form _language_\-_region_. Examples: 'en', 'en-US', 'en-GB', 'zh-CN'. */
+            lang?: string;
+            /** Speaking pitch between 0 and 2 inclusive, with 0 being lowest and 2 being highest. 1.0 corresponds to a voice's default pitch. */
+            pitch?: number;
+            /** Speaking rate relative to the default rate for this voice. 1.0 is the default rate, normally around 180 to 220 words per minute. 2.0 is twice as fast, and 0.5 is half as fast. Values below 0.1 or above 10.0 are strictly disallowed, but many voices will constrain the minimum and maximum rates further—for example a particular voice may not actually speak faster than 3 times normal even if you specify a value larger than 3.0. */
+            rate?: number;
+            /** The TTS event types the voice must support. */
+            requiredEventTypes?: string[];
+            /** The name of the voice to use for synthesis. If empty, uses any available voice. */
+            voiceName?: string;
+            /** Speaking volume between 0 and 1 inclusive, with 0 being lowest and 1 being highest, with a default of 1.0. */
+            volume?: number;
             /**
-             * The type can be 'start' as soon as speech has started, 'word' when a word boundary is reached, 'sentence' when a sentence boundary is reached, 'marker' when an SSML mark element is reached, 'end' when the end of the utterance is reached, 'interrupted' when the utterance is stopped or interrupted before reaching the end, 'cancelled' when it's removed from the queue before ever being synthesized, or 'error' when any other error occurs. When pausing speech, a 'pause' event is fired if a particular utterance is paused in the middle, and 'resume' if an utterance resumes speech. Note that pause and resume events may not fire if speech is paused in-between utterances.
-             * One of: "start", "end", "word", "sentence", "marker", "interrupted", "cancelled", "error", "pause", or "resume"
+             * This function is called with events that occur in the process of speaking the utterance.
+             * @param event The update event from the text-to-speech engine indicating the status of this utterance.
              */
-            type:
-                | "start"
-                | "end"
-                | "word"
-                | "sentence"
-                | "marker"
-                | "interrupted"
-                | "cancelled"
-                | "error"
-                | "pause"
-                | "resume";
+            onEvent?: (
+                event: TtsEvent,
+            ) => void;
         }
 
         /** A description of a voice available for speech synthesis. */
         export interface TtsVoice {
-            /** Optional. The language that this voice supports, in the form language-region. Examples: 'en', 'en-US', 'en-GB', 'zh-CN'. */
-            lang?: string | undefined;
+            /** All of the callback event types that this voice is capable of sending. */
+            eventTypes?: `${EventType}`[];
+            /** The ID of the extension providing this voice. */
+            extensionId?: string;
             /**
-             * Optional. This voice's gender.
-             * One of: "male", or "female"
+             * This voice's gender.
              * @deprecated since Chrome 70. Gender is deprecated and will be ignored.
              */
-            gender?: string | undefined;
-            /** Optional. The name of the voice. */
-            voiceName?: string | undefined;
-            /** Optional. The ID of the extension providing this voice. */
-            extensionId?: string | undefined;
-            /** Optional. All of the callback event types that this voice is capable of sending. */
-            eventTypes?: string[] | undefined;
-            /**
-             * Optional. If true, the synthesis engine is a remote network resource. It may be higher latency and may incur bandwidth costs.
-             * @since Chrome 33
-             */
-            remote?: boolean | undefined;
+            gender?: `${VoiceGender}`;
+            /** The language that this voice supports, in the form language-region. Examples: 'en', 'en-US', 'en-GB', 'zh-CN'. */
+            lang?: string;
+            /** If true, the synthesis engine is a remote network resource. It may be higher latency and may incur bandwidth costs. */
+            remote?: boolean;
+            /** The name of the voice. */
+            voiceName?: string;
         }
 
-        export interface SpeakOptions {
-            /** Optional. Speaking volume between 0 and 1 inclusive, with 0 being lowest and 1 being highest, with a default of 1.0. */
-            volume?: number | undefined;
-            /**
-             * Optional.
-             * If true, enqueues this utterance if TTS is already in progress. If false (the default), interrupts any current speech and flushes the speech queue before speaking this new utterance.
-             */
-            enqueue?: boolean | undefined;
-            /**
-             * Optional.
-             * Speaking rate relative to the default rate for this voice. 1.0 is the default rate, normally around 180 to 220 words per minute. 2.0 is twice as fast, and 0.5 is half as fast. Values below 0.1 or above 10.0 are strictly disallowed, but many voices will constrain the minimum and maximum rates further—for example a particular voice may not actually speak faster than 3 times normal even if you specify a value larger than 3.0.
-             */
-            rate?: number | undefined;
-            /**
-             * Optional. This function is called with events that occur in the process of speaking the utterance.
-             * @param event The update event from the text-to-speech engine indicating the status of this utterance.
-             */
-            onEvent?: ((event: TtsEvent) => void) | undefined;
-            /**
-             * Optional.
-             * Speaking pitch between 0 and 2 inclusive, with 0 being lowest and 2 being highest. 1.0 corresponds to a voice's default pitch.
-             */
-            pitch?: number | undefined;
-            /** Optional. The language to be used for synthesis, in the form language-region. Examples: 'en', 'en-US', 'en-GB', 'zh-CN'. */
-            lang?: string | undefined;
-            /** Optional. The name of the voice to use for synthesis. If empty, uses any available voice. */
-            voiceName?: string | undefined;
-            /** Optional. The extension ID of the speech engine to use, if known. */
-            extensionId?: string | undefined;
-            /**
-             * Optional. Gender of voice for synthesized speech.
-             * One of: "male", or "female"
-             */
-            gender?: string | undefined;
-            /** Optional. The TTS event types the voice must support. */
-            requiredEventTypes?: string[] | undefined;
-            /** Optional. The TTS event types that you are interested in listening to. If missing, all event types may be sent. */
-            desiredEventTypes?: string[] | undefined;
+        /** @deprecated since Chrome 70. Gender is deprecated and is ignored.*/
+        export enum VoiceGender {
+            FEMALE = "female",
+            MALE = "male",
         }
 
-        /** Checks whether the engine is currently speaking. On Mac OS X, the result is true whenever the system speech engine is speaking, even if the speech wasn't initiated by Chrome. */
-        export function isSpeaking(callback?: (speaking: boolean) => void): void;
-        /** Stops any current speech and flushes the queue of any pending utterances. In addition, if speech was paused, it will now be un-paused for the next call to speak. */
-        export function stop(): void;
-        /** Gets an array of all available voices. */
+        /**
+         * Gets an array of all available voices.
+         *
+         * Can return its result via Promise since Chrome Chrome 101
+         */
         export function getVoices(): Promise<TtsVoice[]>;
-        export function getVoices(callback?: (voices: TtsVoice[]) => void): void;
+        export function getVoices(callback: (voices: TtsVoice[]) => void): void;
+
         /**
-         * Speaks text using a text-to-speech engine.
-         * @param utterance The text to speak, either plain text or a complete, well-formed SSML document. Speech engines that do not support SSML will strip away the tags and speak the text. The maximum length of the text is 32,768 characters.
-         * @param callback Optional. Called right away, before speech finishes. Check chrome.runtime.lastError to make sure there were no errors. Use options.onEvent to get more detailed feedback.
+         * Checks whether the engine is currently speaking. On Mac OS X, the result is true whenever the system speech engine is speaking, even if the speech wasn't initiated by Chrome.
+         *
+         * Can return its result via Promise since Chrome Chrome 101
          */
-        export function speak(utterance: string, callback?: Function): void;
+        export function isSpeaking(): Promise<boolean>;
+        export function isSpeaking(callback: (speaking: boolean) => void): void;
+
+        /** Pauses speech synthesis, potentially in the middle of an utterance. A call to resume or stop will un-pause speech. */
+        export function pause(): void;
+
+        /** If speech was paused, resumes speaking where it left off. */
+        export function resume(): void;
+
         /**
          * Speaks text using a text-to-speech engine.
          * @param utterance The text to speak, either plain text or a complete, well-formed SSML document. Speech engines that do not support SSML will strip away the tags and speak the text. The maximum length of the text is 32,768 characters.
          * @param options Optional. The speech options.
-         * @param callback Optional. Called right away, before speech finishes. Check chrome.runtime.lastError to make sure there were no errors. Use options.onEvent to get more detailed feedback.
-         */
-        export function speak(utterance: string, options: SpeakOptions, callback?: Function): void;
-        /**
-         * Pauses speech synthesis, potentially in the middle of an utterance. A call to resume or stop will un-pause speech.
-         * @since Chrome 29
+
+         * Can return its result via Promise since Chrome Chrome 101
          */
-        export function pause(): void;
+        export function speak(utterance: string, options?: TtsOptions): Promise<void>;
+        export function speak(utterance: string, callback: () => void): void;
+        export function speak(utterance: string, options: TtsOptions, callback: () => void): void;
+
+        /** Stops any current speech and flushes the queue of any pending utterances. In addition, if speech was paused, it will now be un-paused for the next call to speak. */
+        export function stop(): void;
+
         /**
-         * If speech was paused, resumes speaking where it left off.
-         * @since Chrome 29
+         * Called when the list of {@link TtsVoice} that would be returned by getVoices has changed.
+         * @since Chrome 124
          */
-        export function resume(): void;
+        const onVoicesChanged: chrome.events.Event<() => void>;
     }
 
     ////////////////////
diff --git a/types/chrome/test/index.ts b/types/chrome/test/index.ts
@@ -1114,26 +1114,61 @@ function testStorage() {
     chrome.storage.sync.getKeys(() => {}).then(() => {});
 }
 
-// https://developer.chrome.com/apps/tts#type-TtsVoice
-async function testTtsVoice() {
-    chrome.tts.getVoices(voices =>
-        voices.forEach(voice => {
-            console.log(voice.voiceName);
-            console.log("\tlang: " + voice.lang);
-            console.log("\tremote: " + voice.remote);
-            console.log("\textensionId: " + voice.extensionId);
-            console.log("\teventTypes: " + voice.eventTypes);
-        })
-    );
+// https://developer.chrome.com/docs/extensions/reference/api/tss
+function testTts() {
+    chrome.tts.EventType.CANCELLED === "cancelled";
+    chrome.tts.EventType.END === "end";
+    chrome.tts.EventType.ERROR === "error";
+    chrome.tts.EventType.INTERRUPTED === "interrupted";
+    chrome.tts.EventType.MARKER === "marker";
+    chrome.tts.EventType.PAUSE === "pause";
+    chrome.tts.EventType.RESUME === "resume";
+    chrome.tts.EventType.SENTENCE === "sentence";
+    chrome.tts.EventType.START === "start";
+    chrome.tts.EventType.WORD === "word";
+
+    chrome.tts.VoiceGender.FEMALE === "female";
+    chrome.tts.VoiceGender.MALE === "male";
+
+    chrome.tts.getVoices(); // $ExpectType Promise<TtsVoice[]>
+    chrome.tts.getVoices(([voice]) => { // $ExpectType void
+        voice.eventTypes; // $ExpectType ("start" | "end" | "word" | "sentence" | "marker" | "interrupted" | "cancelled" | "error" | "pause" | "resume")[] | undefined
+        voice.extensionId; // $ExpectType string | undefined
+        voice.lang; // $ExpectType string | undefined
+        voice.voiceName; // $ExpectType string | undefined
+        voice.remote; // $ExpectType boolean | undefined
+    });
+    // @ts-expect-error
+    chrome.tts.getVoices(() => {}).then(() => {});
 
-    const voices = await chrome.tts.getVoices();
-    voices.forEach(voice => {
-        console.log(voice.voiceName);
-        console.log("\tlang: " + voice.lang);
-        console.log("\tremote: " + voice.remote);
-        console.log("\textensionId: " + voice.extensionId);
-        console.log("\teventTypes: " + voice.eventTypes);
+    chrome.tts.isSpeaking(); // $ExpectType Promise<boolean>
+    chrome.tts.isSpeaking((speaking) => { // $ExpectType void
+        speaking; // $ExpectType boolean
     });
+    // @ts-expect-error
+    chrome.tts.isSpeaking(() => {}).then(() => {});
+
+    chrome.tts.pause(); // $ExpectType void
+
+    chrome.tts.resume(); // $ExpectType void
+
+    const ttsOptions: chrome.tts.TtsOptions = {
+        lang: "en",
+    };
+
+    chrome.tts.speak("Hello, World!"); // $ExpectType Promise<void>
+    chrome.tts.speak("Hello, World!", ttsOptions); // $ExpectType Promise<void>
+    chrome.tts.speak("Hello, World!", () => {}); // $ExpectType void
+    chrome.tts.speak("Hello, World!", ttsOptions, () => {}); // $ExpectType void
+    // @ts-expect-error
+    chrome.tts.speak("Hello, World!", () => {}).then(() => {});
+
+    chrome.tts.stop(); // $ExpectType void
+
+    chrome.tts.onVoicesChanged.addListener(() => {}); // $ExpectType void
+    chrome.tts.onVoicesChanged.removeListener(() => {}); // $ExpectType void
+    chrome.tts.onVoicesChanged.hasListener(() => {}); // $ExpectType boolean
+    chrome.tts.onVoicesChanged.hasListeners(); // $ExpectType boolean
 }
 
 // https://developer.chrome.com/docs/extensions/reference/api/ttsEngine
