feat: allowing the speak method to accept options and deprecating the speakWithOptions method

Author: Mhp23

docs/USAGE.md

@@ -268,12 +268,13 @@ Speech.reset();
 
 ### Speaking Text
 
-Speak a given text using the current global settings.
+Speak a given text using the current global settings, or provide per-utterance options.
 
 **API Definition:**
 
 ```ts
 Speech.speak(text: string): Promise<string>
+Speech.speak(text: string, options: VoiceOptions): Promise<string>
 ```
 
 **Returns:**
@@ -293,41 +294,39 @@ Speech.onFinish(({id: eventId}) => {
 });
 ```
 
----
-
-### Speaking Text with Custom Options
-
-Override global options for a specific utterance.
-
-**API Definition:**
-
 ```ts
-Speech.speakWithOptions(text: string, options: VoiceOptions): Promise<string>
-```
-
-**Returns:**
-
-- A unique utterance ID (string) returned immediately when the utterance is queued. Use it to filter events for this specific speech operation.
-
-**Example Usage:**
-
-```ts
-const id = await Speech.speakWithOptions('Hello!', {
+const id2 = await Speech.speak('Hello!', {
   language: 'en-US',
   pitch: 1.5,
   rate: 0.8,
 });
 
 // Track events specific to this utterance
 Speech.onProgress(({id: eventId, location, length}) => {
-  if (eventId === id) {
+  if (eventId === id2) {
     console.log(`Progress: ${location}/${length}`);
   }
 });
 ```
 
 ---
 
+### Speaking Text with Custom Options (Deprecated)
+
+Override global options for a specific utterance.
+
+**API Definition:**
+
+```ts
+Speech.speakWithOptions(text: string, options: VoiceOptions): Promise<string>
+```
+
+**Notes:**
+
+- Deprecated. Use `Speech.speak(text, options)` instead.
+
+---
+
 ### Controlling Speech
 
 #### **Stop Speech**

src/Speech.ts

@@ -133,22 +133,31 @@ export default class Speech {
     return TurboSpeech.isSpeaking();
   }
   /**
-   * Speaks text using current global options
+   * Speaks text using current global options, or per-utterance options if provided.
    * @param text - The text to synthesize
+   * @param options - Optional voice options overriding global settings for this utterance
    * @returns Promise<string> Resolves with utterance ID when the utterance is queued
    * @throws If text is null or undefined
    * @example
    * const id = await Speech.speak('Hello, world!');
+   * // Or with per-utterance options:
+   * const id2 = await Speech.speak('Hello!', { pitch: 1.5, rate: 0.8 });
    * // Later, use this ID to track events:
    * Speech.onFinish(({id: eventId}) => {
    *   if (eventId === id) console.log('My speech finished');
    * });
    */
-  public static speak(text: string): Promise<string> {
+  public static speak(text: string): Promise<string>;
+  public static speak(text: string, options: VoiceOptions): Promise<string>;
+  public static speak(text: string, options?: VoiceOptions): Promise<string> {
+    if (options !== undefined) {
+      return TurboSpeech.speakWithOptions(text, options);
+    }
     return TurboSpeech.speak(text);
   }
   /**
    * Speaks text with custom options for this utterance only. Uses global options for any settings not provided.
+   * @deprecated Use `Speech.speak(text, options)` instead.
    * @param text - The text to synthesize
    * @param options - Voice options overriding global settings
    * @returns Promise<string> Resolves with utterance ID when the utterance is queued