From 893b23ce900b06556baa1c3fef67e1e36ef2fcad Mon Sep 17 00:00:00 2001
From: Laurens Valk <laurens@pybricks.com>
Date: Mon, 9 Dec 2019 14:15:43 +0100
Subject: [PATCH] api/builtins/Speaker: add speech

---
 doc/api/hubs_ev3brick.inc | 12 +++++++++++-
 pybricks/builtins.py      | 24 ++++++++++++++++++++++++
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/doc/api/hubs_ev3brick.inc b/doc/api/hubs_ev3brick.inc
index 61d942f..6a668c4 100644
--- a/doc/api/hubs_ev3brick.inc
+++ b/doc/api/hubs_ev3brick.inc
@@ -82,9 +82,19 @@
             # Play a sound file from your project folder
             ev3.speaker.play('mysound.wav')
 
+    .. todo:: The following functionality is not yet implemented
+
+    .. automethod:: pybricks._instances.speaker.say
+
+    .. todo:: The following functionality is not yet implemented
+
+    .. automethod:: pybricks._instances.speaker.set_voice_settings
+
+.. todo:: This functionality is not yet implemented
+
 .. rubric:: Using the screen
 
-.. todo:: SCREEN IS NOT YET UPDATED / IMPLEMENTED
+.. todo:: This functionality is not yet implemented
 
 ..  ::
 
diff --git a/pybricks/builtins.py b/pybricks/builtins.py
index a142b85..ef65adf 100644
--- a/pybricks/builtins.py
+++ b/pybricks/builtins.py
@@ -388,6 +388,30 @@ class Speaker():
 
         pass
 
+    def say(self, text):
+        """Say a given text string.
+
+        Arguments:
+            text (str): What to say.
+        """
+
+        pass
+
+    def set_voice_settings(self, language='en', speed=150, variant='m1'):
+        """Configure voice settings used by the ``say`` method.
+
+        Arguments:
+            language (str)::
+                - ``'en'`` (English)
+                - ``'nl'`` (Dutch)
+                - ``'de'`` (German)
+                - TODO: Add all available/supported languages
+            speed (int): Number of words per minute.
+            variant (str): Voice variant. You can choose female voices
+               (``'f1'`` to ``'f5'``) or male voices (``'m1'`` to ``'m7'``).
+        """
+        pass
+
 
 class Light():
     """Control a single-color light."""