// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

[
  {
    "namespace": "tts",
    "description": "Use the <code>chrome.tts</code> API to play synthesized text-to-speech (TTS). See also the related <a href='http://developer.chrome.com/extensions/ttsEngine.html'>ttsEngine</a> API, which allows an extension to implement a speech engine.",
    "types": [
      {
        "id": "TtsEvent",
        "type": "object",
        "description": "An event from the TTS engine to communicate the status of an utterance.",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["start", "end", "word", "sentence", "marker", "interrupted", "cancelled", "error", "pause", "resume"],
            "description": "The type can be 'start' as soon as speech has started, 'word' when a word boundary is reached, 'sentence' when a sentence boundary is reached, 'marker' when an SSML mark element is reached, 'end' when the end of the utterance is reached, 'interrupted' when the utterance is stopped or interrupted before reaching the end, 'cancelled' when it's removed from the queue before ever being synthesized, or 'error' when any other error occurs. When pausing speech, a 'pause' event is fired if a particular utterance is paused in the middle, and 'resume' if an utterance resumes speech. Note that pause and resume events may not fire if speech is paused in-between utterances."
          },
          "charIndex": {
            "type": "number",
            "optional": true,
            "description": "The index of the current character in the utterance."
          },
          "errorMessage": {
            "type": "string",
            "description": "The error description, if the event type is 'error'.",
            "optional": true
          },
          "srcId": {
            "type": "number",
            "description": "An ID unique to the calling function's context so that events can get routed back to the correct tts.speak call.",
            "nodoc": true,
            "optional": true
          },
          "isFinalEvent": {
            "type": "boolean",
            "description": "True if this is the final event that will be sent to this handler.",
            "nodoc": true,
            "optional": true
          }
        }
      },
      {
        "id": "TtsVoice",
        "type": "object",
        "description": "A description of a voice available for speech synthesis.",
        "properties": {
          "voiceName": {
            "type": "string",
            "optional": true,
            "description": "The name of the voice."
          },
          "lang": {
            "type": "string",
            "optional": true,
            "description": "The language that this voice supports, in the form <em>language</em>-<em>region</em>. Examples: 'en', 'en-US', 'en-GB', 'zh-CN'."
          },
          "gender": {
            "type": "string",
            "optional": true,
            "description": "This voice's gender.",
            "enum": ["male", "female"]
          },
          "extensionId": {
            "type": "string",
            "optional": true,
            "description": "The ID of the extension providing this voice."
          },
          "eventTypes": {
            "type": "array",
            "items": {"type": "string"},
            "optional": true,
            "description": "All of the callback event types that this voice is capable of sending."
          }
        }
      }
    ],
    "functions": [
      {
        "name": "speak",
        "type": "function",
        "description": "Speaks text using a text-to-speech engine.",
        "parameters": [
          {
            "type": "string",
            "name": "utterance",
            "description": "The text to speak, either plain text or a complete, well-formed SSML document. Speech engines that do not support SSML will strip away the tags and speak the text. The maximum length of the text is 32,768 characters."
          },
          {
            "type": "object",
            "name": "options",
            "optional": true,
            "description": "The speech options.",
            "properties": {
              "enqueue": {
                "type": "boolean",
                "optional": true,
                "description": "If true, enqueues this utterance if TTS is already in progress. If false (the default), interrupts any current speech and flushes the speech queue before speaking this new utterance."
              },
              "voiceName": {
                "type": "string",
                "optional": true,
                "description": "The name of the voice to use for synthesis. If empty, uses any available voice."
              },
              "extensionId": {
                "type": "string",
                "optional": true,
                "description": "The extension ID of the speech engine to use, if known."
              },
              "lang": {
                "type": "string",
                "optional": true,
                "description": "The language to be used for synthesis, in the form <em>language</em>-<em>region</em>. Examples: 'en', 'en-US', 'en-GB', 'zh-CN'."
              },
              "gender": {
                "type": "string",
                "optional": true,
                "description": "Gender of voice for synthesized speech.",
                "enum": ["male", "female"]
              },
              "rate": {
                "type": "number",
                "optional": true,
                "minimum": 0.1,
                "maximum": 10,
                "description": "Speaking rate relative to the default rate for this voice. 1.0 is the default rate, normally around 180 to 220 words per minute. 2.0 is twice as fast, and 0.5 is half as fast. Values below 0.1 or above 10.0 are strictly disallowed, but many voices will constrain the minimum and maximum rates further&mdash;for example a particular voice may not actually speak faster than 3 times normal even if you specify a value larger than 3.0."
              },
              "pitch": {
                "type": "number",
                "optional": true,
                "minimum": 0,
                "maximum": 2,
                "description": "Speaking pitch between 0 and 2 inclusive, with 0 being lowest and 2 being highest. 1.0 corresponds to a voice's default pitch."
              },
              "volume": {
                "type": "number",
                "optional": true,
                "minimum": 0,
                "maximum": 1,
                "description": "Speaking volume between 0 and 1 inclusive, with 0 being lowest and 1 being highest, with a default of 1.0."
              },
              "requiredEventTypes": {
                "type": "array",
                "items": {"type": "string"},
                "optional": true,
                "description": "The TTS event types the voice must support."
              },
              "desiredEventTypes": {
                "type": "array",
                "items": {"type": "string"},
                "optional": true,
                "description": "The TTS event types that you are interested in listening to. If missing, all event types may be sent."
              },
              "onEvent": {
                "type": "function",
                "optional": true,
                "description": "This function is called with events that occur in the process of speaking the utterance.",
                "parameters": [
                  {
                    "name": "event",
                    "$ref": "TtsEvent",
                    "description": "The update event from the text-to-speech engine indicating the status of this utterance."
                  }
                ]
              }
            }
          },
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "description": "Called right away, before speech finishes. Check chrome.runtime.lastError to make sure there were no errors. Use options.onEvent to get more detailed feedback.",
            "parameters": []
          }
        ]
      },
      {
        "name": "stop",
        "type": "function",
        "description": "Stops any current speech and flushes the queue of any pending utterances. In addition, if speech was paused, it will now be un-paused for the next call to speak.",
        "parameters": []
      },
      {
        "name": "pause",
        "type": "function",
        "description": "Pauses speech synthesis, potentially in the middle of an utterance. A call to resume or stop will un-pause speech.",
        "parameters": []
      },
      {
        "name": "resume",
        "type": "function",
        "description": "If speech was paused, resumes speaking where it left off.",
        "parameters": []
      },
      {
        "name": "isSpeaking",
        "type": "function",
        "description": "Checks whether the engine is currently speaking. On Mac OS X, the result is true whenever the system speech engine is speaking, even if the speech wasn't initiated by Chrome.",
        "parameters": [
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "name": "speaking",
                "type": "boolean",
                "description": "True if speaking, false otherwise."
              }
            ]
          }
        ]
      },
      {
        "name": "getVoices",
        "type": "function",
        "description": "Gets an array of all available voices.",
        "parameters": [
          {
            "type": "function",
            "name": "callback",
            "optional": true,
            "parameters": [
              {
                "type": "array",
                "name": "voices",
                "items": { "$ref": "TtsVoice" },
                "description": "Array of $ref:TtsVoice objects representing the available voices for speech synthesis."
              }
            ]
          }
        ]
      }
    ],
    "events": [
      {
        "name": "onEvent",
        "type": "function",
        "nodoc": true,
        "parameters": [
          {
            "name": "event",
            "$ref": "TtsEvent",
            "description": "The event from the text-to-speech engine indicating the status of this utterance."
          }
        ],
        "description": "Used to pass events back to the function calling speak()."
      }
    ]
  }
]