<voice-elements>
Description: A couple of Web Components that can do amazing stuff using the Web Speech API.

Sorry, your browser do not support the Web Speech API :(

#
<voice
elements>

A couple of Web Components that can do
amazing stuff using the Web Speech API

## Install

### Install the component using Bower

    $ bower install voice-elements

Fork on GitHub Download as ZIP

## <voice-player>

Provides you a simple DOM API to do speech synthesis (text to speech).

In the following demo, we set some content into the text attribute. Then, by using the autoplay attribute, the voice is played when the element loads.

Reload the page to hear it again.

    <voice-player autoplay text="Welcome to the jungle! hahaha just kidding!"></voice-player>

In the following demo, we define a different language by using the accent attribute. When the button is clicked, we call the speak method to trigger the audio.

    <voice-player id="mi-elemento" accent="es-ES" text="Me gusta la gasolina"></voice-player>

    <script>
    var form = document.querySelector('#mi-form'),
        element = document.querySelector('#mi-elemento');

    form.addEventListener('submit', function(e) {
        e.preventDefault();
        element.speak();
    });
    </script>

In the following demo, the text attribute is set according to the input value. When the form is submitted, we call the speak method to trigger the audio.

    <voice-player id="player-element" text=""></voice-player>

    <script>
    var form = document.querySelector('#player-form'),
        input = document.querySelector('#player-input'),
        element = document.querySelector('#player-element');

    input.addEventListener('input', function(e) {
        element.setAttribute('text', input.value);
    });

    form.addEventListener('submit', function(e) {
        e.preventDefault();
        element.speak();
    });
    </script>

## Options

Attribute | Options | Default | Description
--- | --- | --- | ---
autoplay | boolean | false | Specifies if the audio should play when page loads.
accent | en-US, en-GB, es-ES, fr-FR, it-IT, de-DE, ja-JP, ko-KR, zh-CN | en-US | Specifies the language to be synthesized and spoken.
text | string | You are awesome | Specifies the text to be synthesized and spoken.

## Methods

Method | Parameters | Returns | Description
--- | --- | --- | ---
speak() | None | Nothing | Triggers the voice audio to be played.
cancel() | None | Nothing | Triggers the voice audio to be canceled.
pause() | None | Nothing | Triggers the voice audio to be paused.
resume() | None | Nothing | Triggers the voice audio to be resumed.

## Events

Event | Description
--- | ---
onstart | Triggers when the voice begun to be spoken.
onend | Triggers when the voice completed to be spoken.
onerror | Triggers when the voice player detects an error.
onpause | Triggers when the voice player is resumed.
onresume | Triggers when the voice player is resumed.

## Features

### Voice recognition (speech to text)

Voice recognition is the translation of spoken words into text. This is achieved in the browser by using the SpeechRecognition interface from the Web Speech API.

### Speech synthesis (text to speech)

Speech synthesis is the conversion of language text into speech. This is achieved in the browser by using then SpeechSynthesis interface from the Web Speech API.

## <voice-recognition>

Provides you a simple DOM API to do voice recognition (speech to text).

In the following demo, we trigger the voice recognition by using the start method when the user submits the form. Then, we add a listener to the result event to fetch the recognized content and put it into the textarea.

Click "start", authorize, and say something...

    <voice-recognition id="recognition-element"></voice-recognition>

    <script>
    var form = document.querySelector('#recognition-form'),
        input = document.querySelector('#recognition-input'),
        element = document.querySelector('#recognition-element');

    form.addEventListener('submit', function(e) {
        e.preventDefault();
        element.start();
    });

    element.addEventListener('result', function(e) {
        input.textContent = e.detail.result;
    });
    </script>

## Options

Attribute | Options | Default | Description
--- | --- | --- | ---
continuous | boolean | false | Specifies if the recognition should continue when the user pauses while speaking.
text | string |  | Returns the recognized text.

## Methods

Method | Parameters | Returns | Description
--- | --- | --- | ---
start() | None | Nothing | Starts the voice recognition.
stop() | None | Nothing | Requests to recognition service to stop listening to more audio.
abort() | None | Nothing | Requests to immediately stop listening and stop recognizing.

## Events

Event | Description
--- | ---
onstart | Triggers when the recognition begins.
onerror | Triggers when there's a recognition error.
onend | Triggers when the recognition ends.
onresult | Triggers when there's a recognition result.

## Usage

### 1. Import Web Components' polyfill

    <script src="bower_components/platform/platform.js"></script>

### 2. Import Custom Element

    <link rel="import" href="bower_components/voice-elements/dist/voice-player.html">
    <link rel="import" href="bower_components/voice-elements/dist/voice-recognition.html">

### 3. Start using it!

    <voice-player></voice-player>
    <voice-recognition></voice-recognition>