Write documentation

mealie/routes/voice/stt_route.py

@@ -13,12 +13,16 @@
 
 @controller(router)
 class STTController(BasePublicController):
+    """Controller for speech to text API"""
+
     @cached_property
     def service(self) -> STTService:
+        """The speech to text service"""
         return STTService()
 
     @router.post("", response_model=SuccessResponse)
     async def speech_to_text(self, audio: UploadFile):
+        """Convert passed in audio to text"""
         try:
             async with self.service as service:
                 message = await service.transcribe(audio)

mealie/routes/voice/tts_route.py

@@ -14,12 +14,16 @@
 
 @controller(router)
 class TTSController(BasePublicController):
+    """Controller for text to speech API"""
+
     @cached_property
     def service(self) -> TTSService:
+        """The text to speech service"""
         return TTSService()
 
     @router.post("")
     async def text_to_speech(self, text: str):
+        """Convert passed in text into speech"""
         try:
             async with self.service as service:
                 filename = await service.synthesize(text)

mealie/services/voice_services/stt_service.py

@@ -11,33 +11,43 @@
 
 
 class STTService(BaseService):
+    """A service for performing speech to text conversion"""
+
     client: AsyncClient
+    """The wyoming protocol client providing speech to text"""
     connected: bool = False
+    """Whether the client is connected"""
 
     def __init__(self):
+        """Initialize the speech to text client"""
         super().__init__()
         self.client = AsyncClient.from_uri(self.settings.SPEECH_TO_TEXT_URI)
 
     async def __aenter__(self):
+        """Set up a connection asyncronously"""
         await self.connect()
         return self
 
     async def __aexit__(self, exc_type, exc_value, traceback):
+        """Set up a connection asyncronously"""
         await self.disconnect()
 
     async def connect(self):
+        """Set up a connection asyncronously"""
         if self.connected:
             return
         await self.client.connect()
         self.connected = True
 
     async def disconnect(self):
+        """Destroy the connection asyncronously"""
         if not self.connected:
             return
         await self.client.disconnect()
         self.connected = False
 
     async def transcribe(self, audio: UploadFile) -> str | None:
+        """Transcribe an uploaded audio file to text"""
         transcribe_event = Transcribe(self.settings.SPEECH_TO_TEXT_MODEL, self.settings.SPEECH_TO_TEXT_LANGUAGE)
         await self.client.write_event(transcribe_event.event())
         with wave.open(audio.file, "rb") as audio_file:

mealie/services/voice_services/tts_service.py

@@ -9,34 +9,49 @@
 
 
 class TTSService(BaseService):
+    """A service for performing text to speech conversion"""
+
     client: AsyncClient
+    """The wyoming protocol client providing text to speech"""
     connected: bool = False
+    """Whether the client is connected"""
+    voice: SynthesizeVoice
+    """The voice to use for synthesizing speech"""
 
     def __init__(self):
+        """Initialize the text to speech client and voice"""
         super().__init__()
         self.client = AsyncClient.from_uri(self.settings.TEXT_TO_SPEECH_URI)
         self.voice = SynthesizeVoice(self.settings.TEXT_TO_SPEECH_VOICE)
 
     async def __aenter__(self):
+        """Set up a connection asyncronously"""
         await self.connect()
         return self
 
     async def __aexit__(self, exc_type, exc_value, traceback):
+        """Destroy the connection asyncronously"""
         await self.disconnect()
 
     async def connect(self):
+        """Set up a connection asyncronously"""
         if self.connected:
             return
         await self.client.connect()
         self.connected = True
 
     async def disconnect(self):
+        """Destroy the connection asyncronously"""
         if not self.connected:
             return
         await self.client.disconnect()
         self.connected = False
 
     async def synthesize(self, text: str) -> str:
+        """
+        Synthesize speech from text. Returns the filename of a temporary file.
+        Caller is responsible for cleaning file up.
+        """
         synthesize_event = Synthesize(text, self.voice)
         await self.client.write_event(synthesize_event.event())
         wave_file = tempfile.NamedTemporaryFile("wb", delete=False)