Butler.js NPM | npm.io

###What is Butler?

Butler.js is the voice driven, portable butler for your personal needs.

You can easily customize it to your needs and he will never betray you.

Butler is developed with the aim of making life simpler for developers and designers, specifically in debugging/drafting.

What you would have done before through the keyboard and scripts can now be done by commanding Butler by voice.

With a bit of healthy humor and fun.

###Why Butler?

Many libraries offer the possibility to activate voice commands, Butler offers the same but it starts with already defined commands that can help you debugging or anyway to have fun while debugging and make your life simpler in the browser daily routine.

Plus you have the ability to write your own plugins (and this is very easy) to expand the abilities of Butler at your leisure.

###Installation

####HTML

<!DOCTYPE html>
<html>
<head>
<script src="../path/to/butler.min.js"></script>
</head>

####Bower

bower install butler.js

####Npm

npm install butler.js

###Usage

document.addEventListener("DOMContentLoaded", function() {
  Butler.start();
});

###Demo Live demo

Commands

Default voice commands you can abuse of. (many others are coming...)

####Butler Common commands for Butler

Command	Result
Butler speak	Turn on Butler voice
Butler silence	Turn off Butler voice

####Selector Commands to select, visualize and manipulate the DOM elements

Command	Result
Selector on	Turn on selector highlighter
Selector off	Turn off selector highlighter
Selector next	Select next element in the DOM
Selector back	Select previous element in the DOM
Selector next id :detection:	Select next element in the DOM by detected id value
Selector next class :detection:	Select next element in the DOM by detected class name
Selector next tag :detection:	Select next element by detected tag name
Selector back id :detection:	Select previous element by detected id value
Selector back class :detection:	Select next element by detected class name
Selector back tag :detection:	Select next element by detected tag name
Selector add class :detection:	Add detected class name to the current selected DOM element
Selector remove class :detection:	Remove detected class name from the current selected DOM element
Selector add id :detection:	Add detected id value to the current selected DOM element
Selector put value :detection:	Add detected value to the current selected DOM element (helpful for inputs)
Selector insert text :detection:	Insert detected text inside the current selected DOM element
Selector empty text	Remove all the text from the current selected DOM element
Selector copy text	Copy all the text from the current selected DOM element
Selector paste text	Paste the previously copied text to the current selected DOM element
Selector make editable	Make the current selected DOM element editable
Selector not editable	Make the current selected DOM element not editable
Selector make disabled	Make the current selected DOM element disabled
Selector not disabled	Make the current selected DOM element not disabled
Selector clone	Clone the current selected DOM element
Selector append clone	Append the cloned element to the current selected DOM element
Selector prepend clone	Prepend the cloned element to the current selected DOM element
Selector delete	Delete the current selected DOM element
Selector hide	Hide the current selected DOM element
Selector show	Show the current selected DOM element
Selector let me choose	Select yourself which DOM element by clicking the element
Selector which	Show and alert the current selected DOM element informations

####Trigger

Commands to trigger events and actions

Command	Result
Trigger click	Trigger click on the current selected DOM element
Trigger focus	Trigger focus on the current selected DOM element
Trigger fade	Trigger fade on the current selected DOM element
Trigger pin	Trigger pin on the current selected DOM element
Trigger blur	Trigger blur on the current selected DOM element
Trigger submit	Trigger submit on the current selected DOM element
Trigger select	Trigger select on the current selected DOM element
Trigger change	Trigger change on the current selected DOM element
Trigger show	Trigger show on the current selected DOM element
Trigger reset	Trigger reset on the current selected DOM element
Trigger play	Trigger play on the current selected DOM element
Trigger pause	Trigger play on the current selected DOM element
Trigger mouse over	Trigger mouseover on the current selected DOM element
Trigger mouse up	Trigger mouseup on the current selected DOM element
Trigger mouse down	Trigger mousedown on the current selected DOM element
Trigger mouse leave	Trigger mouseover on the current selected DOM element
Trigger mouse move	Trigger mousemove on the current selected DOM element
Trigger mouse enter	Trigger mouseenter on the current selected DOM element
Trigger mouse out	Trigger mouseout on the current selected DOM element
Trigger drag	Trigger drag on the current selected DOM element
Trigger drag start	Trigger dragstart on the current selected DOM element
Trigger drag end	Trigger dragend on the current selected DOM element
Trigger drag enter	Trigger dragenter on the current selected DOM element
Trigger drag leave	Trigger dragleave on the current selected DOM element
Trigger drag over	Trigger dragmove on the current selected DOM element
Trigger drop	Trigger drop on the current selected DOM element
Trigger touch start	Trigger touchstart on the current selected DOM element
Trigger touch end	Trigger touchend on the current selected DOM element
Trigger touch enter	Trigger touchenter on the current selected DOM element
Trigger touch leave	Trigger touchleave on the current selected DOM element
Trigger touch move	Trigger touchmove on the current selected DOM element
Trigger touch cancel	Trigger touchcancel on the current selected DOM element
Trigger scroll y	Trigger Y scroll on the current selected DOM element
Trigger scroll x	Trigger X scroll on the current selected DOM element

####Window

Commands to manipulate, trigger window events and actions

Command	Result
Window scroll y	Trigger window Y scroll
Window scroll x	Trigger window X scroll
Window size	Alert window dimensions

####Location Commands to manipulate, navigate urls and history

Command	Result
Location refresh	Location refresh
Location back	Go to previous location url
Location forward	Go to next location url
Location hashbang	Add hashbang at the end of the location url

####Navigator

Commands to manipulate, trigger window.navigator

Command	Result
Navigator go online	Set online status
Navigator go offline	Set offline status
Navigator vibrate	Vibrate device
Navigator which	Show and alert navigator informations

####Browser

Commands to manipulate and interact with the browser

Command	Result
Browser clean cookies	Clean browser cookies
Browser clean session storage	Clean browser session storage
Browser clean local storage	Clean browser local storage

###i18n Butler can be used in various languages available here (Soon there will be more languages)

If you want Butler to understand italian language for example, just include the i18n italian file after butler main file:

<script src="butler.min.js"></script>
<script src="butler.it_IT.js"></script>

This way all the default commands gets translated to italian, you can check translations for each i18n file from their README file

###Tools Butler exposes some good stuff you can interact with.

You can check them all by:

window.console.info(Butler);

####Butler.Highlighter Highlighter is the Butler selector (taken from Highlighter.js), is the DOM surfer who take trace of the selected and current elements.

window.console.info('Which element are you on Butler?', Butler.Highlighter.element);

####Butler.Clipboard Clipboard is where Butler saves the last copied text and/or cloned element.

window.console.info('What you copied or cloned Butler?', Butler.Clipboard);

####Butler.Voice Voice is the Butler voice, simple.

Butler.Voice.volume = 0.5;
Butler.Voice.play();

####Butler.Commands Commands is the Object containing all the default Butler voice commands.

window.console.info('Which commands do you know Butler?', Butler.Commands);

If you need some of them to be run just do:

var ButlerCommand = Butler.Commands['selector on'];
ButlerCommand();

###Events Available events

document.addEventListner('Butler:start', function (data) {
	console.info('Butler is started and microfone is allowed', data);
});

document.addEventListner('Butler:end', function (data) {
	console.info('Butler has stopped working', data);
});

document.addEventListner('Butler:detection', function (data) {
	console.info('Butler has new detections', data);
});

document.addEventListner('Butler:detection-match', function (data) {
	console.log('Butler detection is matching', data);
});

document.addEventListner('Butler:detection-not-match', function (data) {
	console.log('Butler detection is not matching', data);
});

document.addEventListner('Butler:error', function (error) {
	console.error('Butler returned an error', error);
});

###Plugins Writing a plugin is very simple, all you have to do is to define new commands using the plug() method.

If you want to access Butler tools have a look here

####Plugin commands Please refer to annyang documentation to define new commands

Example

butler.plugin.js

document.addEventListener("DOMContentLoaded", function () {
   Butler.plug({
    'do something when i say this sentence': function callback(){
       window.alert('You said that sentence');
    }
  });
});

index.html

<head>
<script src="butler.min.js"></script>
<script src="butler.plugin.js"></script>
<script>
document.addEventListener("DOMContentLoaded", function () {
  Butler.start();
});
</script>
</head>

Now all the butler.plugin.js defined commands and callbacks are plugged and can be used.

###Debug Enable debug mode

document.addEventListener("DOMContentLoaded", function () {
  Butler.start({
   'debug':true
  });
});

###Browser Support

Google Chrome (latest versions)

http://caniuse.com/#feat=web-speech

###Contributing

We would be pleased if you help to develop and grow the project more and more.

The goal is to make the life of programmers and designers more simple and fun, so any suggestion, PR, and specially plugin is welcome and appreciated a lot.

Thank you.

###License The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

####Gtk

Not ready for a production project
Default commands may be changed or modified at any time, others will come soon
The Speech Detection is still very slow sometimes, using https:// will be slighty faster
If you have multiple tabs working on speech recognition and microphone there will be problems, please use Butler on a single browser tab and close the other tabs that are asking for your microphone

####Thank you

to Google and Google developers, for the awesome webkit-speech API
to https://github.com/TalAter/annyang developers and maintainers for the awesome library.