Cleanup examples and fix VoicesManager types (#332)

Signed-off-by: rany <[email protected]>

examples/dynamic_voice_selection.py → examples/async_audio_gen_with_dynamic_voice_selection.py

@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
 
-"""
-Example of dynamic voice selection using VoicesManager.
-"""
+"""Simple example to generate an audio file with randomized
+dynamic voice selection based on attributes such as Gender,
+Language, or Locale."""
 
 import asyncio
 import random

examples/basic_generation.py → examples/async_audio_gen_with_predefined_voice.py

@@ -1,8 +1,6 @@
 #!/usr/bin/env python3
 
-"""
-Basic example of edge_tts usage.
-"""
+"""Simple example to generate audio with preset voice using async/await"""
 
 import asyncio
 

examples/streaming_with_subtitles.py → examples/async_audio_streaming_with_predefined_voice_and_subtitles.py

@@ -1,11 +1,7 @@
 #!/usr/bin/env python3
 
-"""
-Streaming TTS example with subtitles.
-
-This example is similar to the example basic_audio_streaming.py, but it shows
-WordBoundary events to create subtitles using SubMaker.
-"""
+"""Example showing how to use use .stream() method to get audio chunks
+and feed them to SubMaker to generate subtitles"""
 
 import asyncio
 

examples/basic_sync_generation.py → examples/sync_audio_gen_with_predefined_voice.py

@@ -1,8 +1,7 @@
 #!/usr/bin/env python3
 
-"""
-Basic example of edge_tts usage in synchronous function
-"""
+"""Sync variant of the example for generating audio with a predefined voice"""
+
 
 import edge_tts
 

examples/basic_sync_audio_streaming.py → examples/sync_audio_streaming_with_predefined_voice_subtitles.py

@@ -1,26 +1,30 @@
 #!/usr/bin/env python3
 
-"""
-Basic audio streaming example for sync interface
-
-"""
+"""Sync variant of the async .stream() method to
+get audio chunks and feed them to SubMaker to
+generate subtitles"""
 
 import edge_tts
 
 TEXT = "Hello World!"
 VOICE = "en-GB-SoniaNeural"
 OUTPUT_FILE = "test.mp3"
+SRT_FILE = "test.srt"
 
 
 def main() -> None:
-    """Main function to process audio and metadata synchronously."""
+    """Main function"""
     communicate = edge_tts.Communicate(TEXT, VOICE)
+    submaker = edge_tts.SubMaker()
     with open(OUTPUT_FILE, "wb") as file:
         for chunk in communicate.stream_sync():
             if chunk["type"] == "audio":
                 file.write(chunk["data"])
             elif chunk["type"] == "WordBoundary":
-                print(f"WordBoundary: {chunk}")
+                submaker.feed(chunk)
+
+    with open(SRT_FILE, "w", encoding="utf-8") as file:
+        file.write(submaker.get_srt())
 
 
 if __name__ == "__main__":

src/edge_tts/communicate.py

@@ -518,7 +518,7 @@ async def save(
                     json.dump(message, metadata)
                     metadata.write("\n")
 
-    def stream_sync(self) -> Generator[Dict[str, Any], None, None]:
+    def stream_sync(self) -> Generator[TTSChunk, None, None]:
         """Synchronous interface for async stream method"""
 
         def fetch_async_items(queue: Queue) -> None:  # type: ignore

src/edge_tts/typing.py

@@ -82,3 +82,11 @@ class VoiceManagerVoice(Voice):
     """Voice data for VoiceManager."""
 
     Language: str
+
+
+class VoiceManagerFind(TypedDict):
+    """Voice data for VoiceManager.find()."""
+
+    Gender: NotRequired[Literal["Female", "Male"]]
+    Locale: NotRequired[str]
+    Language: NotRequired[str]

src/edge_tts/voices.py

@@ -7,10 +7,11 @@
 
 import aiohttp
 import certifi
+from typing_extensions import Unpack
 
 from .constants import SEC_MS_GEC_VERSION, VOICE_HEADERS, VOICE_LIST
 from .drm import DRM
-from .typing import Voice, VoiceManagerVoice
+from .typing import Voice, VoiceManagerFind, VoiceManagerVoice
 
 
 async def __list_voices(
@@ -94,7 +95,9 @@ def __init__(self) -> None:
         self.called_create: bool = False
 
     @classmethod
-    async def create(cls: Any, custom_voices: Optional[List[Voice]] = None) -> Any:
+    async def create(
+        cls: Any, custom_voices: Optional[List[Voice]] = None
+    ) -> "VoicesManager":
         """
         Creates a VoicesManager object and populates it with all available voices.
         """
@@ -106,7 +109,7 @@ async def create(cls: Any, custom_voices: Optional[List[Voice]] = None) -> Any:
         self.called_create = True
         return self
 
-    def find(self, **kwargs: Any) -> List[VoiceManagerVoice]:
+    def find(self, **kwargs: Unpack[VoiceManagerFind]) -> List[VoiceManagerVoice]:
         """
         Finds all matching voices based on the provided attributes.
         """