{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import panel as pn\n",
    "\n",
    "pn.extension()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `TextToSpeech` Widget provides brings *text to speech* to Panel. It wraps the wraps the [HTML5 SpeechSynthesis API](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis) and [HTML SpeechSynthesisUtterance API](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesisUtterance). \n",
    "\n",
    "An *utterance* is the smallest unit of speech in spoken language analysis. The `Utterance` provides fine grained control over the `text`, `voice`, `volume`, `pitch` and `rate`.\n",
    "\n",
    "\n",
    "#### Parameters:\n",
    "\n",
    "##### Core\n",
    "\n",
    "* **``value``** (str): The text that will be synthesised when the utterance is spoken. The text may be provided as plain text, or a well-formed SSML document\n",
    "* **``auto_speak``** (boolean): Whether or not to speak automatically whenever the value changes. Default it True.\n",
    "* **``lang``** (str): The language of the utterance.\n",
    "* **``voice``** (SpeechSynthesisVoice): The voice that will be used to speak the utterance.\n",
    "* **``pitch``** (float): The pitch at which the utterance will be spoken at. A number between 0 and 2. Default is 1\n",
    "* **``rate``** (float): The speed at which the utterance will be spoken at. A number between 0.1 and 10. Default is 1\n",
    "* **``volume``** (float): The volume that the utterance will be spoken at. A number between 0 and 1. Default is 1\n",
    "\n",
    "##### Actions\n",
    "\n",
    "* **``speak``**: Speaks the utterance. Note an utterance is also spoken whenever you change the `value`.\n",
    "* **``cancel``** (): Removes all Utterances from the Utterance queue.\n",
    "* **``pause``** (): Puts the SpeechSynthesis object into a paused state.\n",
    "* **``resume``** (): Puts the SpeechSynthesis object into a non-paused state: resumes it if it was already paused.\n",
    "\n",
    "##### Readonly Parameters:\n",
    "\n",
    "* **``voices``** (List[Voice]): Returns a list of Voice objects representing all the available voices in the current device.\n",
    "\n",
    "The `voices` parameter is populated by your browser and are not available before 1) The `TextToSpeech` instance is included in your app 2) the app has loaded and 3) the browser has loaded its list of `voices`. The available voices depend on your OS and browser.\n",
    "\n",
    "* **``paused``** (boolean): Returns true if the TextToSpeech object is in a paused state.\n",
    "* **``pending``** (boolean): Returns true if the utterance queue contains as-yet-unspoken\n",
    "        utterances.\n",
    "* **``speaking``** (boolean): returns true if an utterance is currently in the process of being\n",
    "        spoken — even if TextToSpeech is in a paused state.\n",
    "        \n",
    "The `paused`, `pending` and `speaking` parameters are being updated by your browser every 1 sec only. So they arrive with a small time lag.\n",
    "\n",
    "___"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Instantiate and display the `TextToSpeech` widget without any text:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "basic_speaker = pn.widgets.TextToSpeech(name=\"Speech Synthesis\")\n",
    "basic_speaker"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As long as `auto_speak` is true setting the `value` will cause it to speak:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "basic_speaker.value = \"Hello Panel World\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also trigger speaking by setting the `speak` parameter to `True`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "basic_speaker.speak = True"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let us create a longer text:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "TEXT = \"\"\"By Aesop\n",
    "\n",
    "There was a time, so the story goes, when all the animals lived together in harmony. The lion didn’t chase the oxen, the wolf didn’t hunt the sheep, and owls didn’t swoop on the mice in the field.\n",
    "\n",
    "Once a year they would get together and choose a king, who would then reign over the animal kingdom for the next twelve months. Those animals who thought they would like a turn at being king would put themselves forward and would make speeches and give demonstrations of their prowess or their wisdom. Then all the animals gathered together would vote, and the animal with the most votes was crowned king. That’s probably where us humans got the idea of elections!\n",
    "\n",
    "Now, monkey knew very well that he was neither very strong nor very wise, and he was not exactly a great orator, but, boy, could he dance! So he did what he does best, and he danced acrobatically and energetically, performing enormous leaps, back somersaults and cartwheels that truly dazzled his audience. Compared to monkey, the elephant was grave and cumbersome, the lion was powerful and authoritarian, and the snake was sly and sinister.\n",
    "\n",
    "Nobody who was there remembers exactly how it happened, but somehow monkey scraped through with a clear majority of all the votes cast, and he was announced the king of the animal kingdom for the coming year. Most of the animals seemed quite content with this outcome, because they knew that monkey would not take his duties too seriously and make all kinds of onerous demands on them, or demand too much of a formal show of obedience. But there were some who thought that the election of monkey diminished the stature of the kingship, and one of these was fox; in fact fox was pretty disgusted, and he didn’t mind who knew it. So he set about concocting a scheme to make monkey look stupid.\n",
    "\n",
    "He gathered together some fine fresh fruit from the forest, mangos, figs and dates, and laid them out on a trap he’d found. He waited for the monkey to pass by, and called out to him: “Sire, look at these delicious dainty morsels I discovered here by the wayside. I was tempted to gorge myself on them, but then I remembered fruits are your favourite repast, and I thought I should keep them for you, our beloved king!”\n",
    "\n",
    "Monkey could not resist either the flattery or the fruit, and just managed to compose himself long enough to whisper a hurried “Why, thank you, Mr Fox” and made a beeline for the fruit. “Swish” and “Clunk” went the trap, and “AAAYYY AAAYYY” went our unfortunate monkey king, the trap firmly clasped around his paw.\n",
    "\n",
    "Monkey bitterly reproached fox for leading him into such a dangerous situation, but fox just laughed and laughed. “You call yourself king of all the animals,” he cried, “and you allow yourself to be taken in just like that!”\n",
    "\n",
    "Aesop\n",
    "\"\"\"\n",
    "\n",
    "text_to_speech = pn.widgets.TextToSpeech(name=\"Text to Speech Widget\", value=TEXT, auto_speak=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And controls to the widget so you can test what the various parameters do:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "text = pn.Param(text_to_speech.param.value, widgets={\"value\": {\"widget_type\": pn.widgets.TextAreaInput, \"height\": 300}})\n",
    "\n",
    "pn.Row(text_to_speech.controls(jslink=False), text, text_to_speech, width=600)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Try changing the `value`, `lang`, `voice` etc."
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}