Plugin release

ion-sound.jquery.json

@@ -0,0 +1,33 @@
+{
+    "name": "ion-sound",
+    "version": "1.0.0",
+    "title": "Ion.Sound",
+    "description": "Plugin for playing sounds on events",
+    "keywords": [
+        "sound",
+        "sounds",
+        "audio",
+        "html5",
+        "events",
+        "alert",
+        "ui"
+    ],
+    "author": {
+        "name": "IonDen",
+        "url": "https://github.com/IonDen",
+        "email": "[email protected]"
+    },
+    "licenses": [
+        {
+            "type": "MIT",
+            "url": "http://ionden.com/a/plugins/licence-en.html"
+        }
+    ],
+    "homepage": "https://github.com/IonDen/ion.sound",
+    "docs": "https://github.com/IonDen/ion.sound/blob/master/readme.md",
+    "demo": "http://ionden.com/a/plugins/ion.sound/en.html",
+    "download": "http://ionden.com/a/plugins/ion.sound/ion.sound-1.0.0.zip",
+    "dependencies": {
+        "jquery": ">=1.9"
+    }
+}

js/ion-sound/ion.sound.js

@@ -0,0 +1,92 @@
+// Ion.Sound
+// version 1.0.0 Build: 3
+// © 2013 Denis Ineshin | IonDen.com
+//
+// Project page:    http://ionden.com/a/plugins/ion.sound/en.html
+// GitHub page:     https://github.com/IonDen/ion.sound
+//
+// Released under MIT licence:
+// http://ionden.com/a/plugins/licence-en.html
+// =====================================================================================================================
+
+var ion = ion || {};
+
+ion.sound = {
+    init: function(options){
+        var settings = $.extend({
+            sounds: [
+                "beer_can_opening",
+                "bell_ring",
+                "branch_break",
+                "button_click",
+                "button_click_on",
+                "button_push",
+                "button_tiny",
+                "camera_flashing",
+                "computer_error",
+                "door_bell",
+                "light_bulb_breaking",
+                "metal_plate",
+                "pop_cork",
+                "staple_gun",
+                "water_droplet"
+            ],
+            path: "static/sounds/",
+            multiPlay: true,
+            volume: "0.5"
+        }, options);
+
+        var i,
+            soundsNum = settings.sounds.length,
+            self = this,
+            canMp3,
+            url;
+
+        this.sounds = {};
+        this.playing = false;
+        this.multiPlay = settings.multiPlay;
+
+        var createSound = function(name){
+            self.sounds[name] = new Audio();
+            canMp3 = self.sounds[name].canPlayType("audio/mp3");
+            if(canMp3 === "probably" || canMp3 === "maybe") {
+                url = settings.path + name + ".mp3";
+            } else {
+                url = settings.path + name + ".ogg";
+            }
+
+            $(self.sounds[name]).prop("src", url);
+            self.sounds[name].load();
+            self.sounds[name].volume = settings.volume;
+        };
+
+        if(typeof Audio === "function" || typeof Audio === "object") {
+            for(i = 0; i < soundsNum; i += 1){
+                createSound(settings.sounds[i]);
+            }
+        }
+    },
+    play: function(name){
+        var $sound = this.sounds[name],
+            playingInt,
+            self = this;
+
+        if(typeof $sound === "object") {
+
+            if(!this.multiPlay && !this.playing) {
+                $sound.play();
+                this.playing = true;
+
+                playingInt = setInterval(function(){
+                    if($sound.ended) {
+                        clearInterval(playingInt);
+                        self.playing = false;
+                    }
+                }, 250);
+            } else if(this.multiPlay) {
+                $sound.play();
+            }
+
+        }
+    }
+};

readme.md

@@ -0,0 +1,116 @@
+# Ion.Sound 1.0.0
+
+> English description | <a href="readme.ru.md">Описание на русском</a>
+
+Plugin for playing sounds on events.
+* <a href="http://ionden.com/a/plugins/ion.sound/index.html">Project page and demos</a>
+* <a href="http://ionden.com/a/plugins/ion.sound/ion.sound-1.0.0.zip">Download ion.sound-1.0.0.zip</a>
+
+***
+
+## Description
+* Crossbrowser support: Google Chrome, Mozilla Firefox, Opera, Safari, IE(9.0+) and mobile browsers
+* <a href="https://github.com/IonDen/ion.sound">GitHub Page</a>.
+* Ion.Sound freely distributed under terms of <a href="http://ionden.com/a/plugins/licence-en.html" target="_blank">MIT licence</a>.
+* Ion.Sound includes 15 free sounds
+
+Today websites are full of events (new mail, new chat-message, content update etc.). Often it is not enough to indicate this events only visually to get user attention. You need sounds! This library, made for playing small sounds, will help you with this task.
+
+
+## Dependencies
+* <a href="http://jquery.com/" target="_blank">jQuery 1.9+</a>
+
+
+## Usage
+Import this libraries:
+* jQuery
+* ion.sound.min.js
+
+Prepare sound-files (15 sounds are included) and put them in some folder (eg. "sounds"):
+* my_cool_sound.mp3
+* my_cool_sound.ogg
+It is not enough to have only Mp3-file, you should make Ogg-file too, because not all browsers support Mp3. You can easily convert you Mp3-s to Ogg-s <a href="http://media.io/" target="_blank">online</a>.
+
+
+## Initialisation
+To initialise plugin call this method:
+```javascript
+ion.sound.init();
+```
+
+And play sound!
+```javascript
+ion.sound.play("my_cool_sound");
+```
+
+
+## Settings
+<table class="options">
+    <thead>
+        <tr>
+            <th>Settings</th>
+            <th>Default</th>
+            <th>Description</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>sounds</td>
+            <td>[Array of 15 sounds]</td>
+            <td>Optional property, you can set your own sounds collection here.</td>
+        </tr>
+        <tr>
+            <td>path</td>
+            <td>"static/sounds/"</td>
+            <td>Optional property, set path to folder with sounds.</td>
+        </tr>
+        <tr>
+            <td>multiPlay</td>
+            <td>true</td>
+            <td>Optional property, if set to <code>false</code>, will allow plugin to play only 1 sound at once.</td>
+        </tr>
+        <tr>
+            <td>volume</td>
+            <td>0.5</td>
+            <td>Optional property, will set base volume from 0.0 to 1.0</td>
+        </tr>
+    </tbody>
+</table>
+
+An example of a customised plugin:
+```javascript
+ion.sound.init({
+    sounds: [                       // set sounds names
+        "beer_can_opening",
+        "bell_ring",
+        "branch_break",
+        "button_click",
+        "button_click_on",
+        "button_push",
+        "button_tiny",
+        "camera_flashing",
+        "computer_error",
+        "door_bell",
+        "light_bulb_breaking",
+        "metal_plate",
+        "pop_cork",
+        "staple_gun",
+        "water_droplet"
+    ],
+    path: "sounds/",                // set path to sounds
+    multiPlay: false,               // playing only 1 sound at once
+    volume: "0.3"                   // not so loud please
+});
+```
+
+
+Playing sound on button click:
+```javascript
+$("#myButton").on("click", function(){
+    ion.sound.play("button_tiny");
+});
+```
+
+
+## Update history
+* September 07, 2013 - Plugin release

readme.ru.md

@@ -0,0 +1,113 @@
+# Ion.Sound 1.0.0
+
+> <a href="readme.md">English description</a> | Описание на русском
+
+Плагин для воспроизведения звуков событий.
+* <a href="http://ionden.com/a/plugins/ion.sound/index.html">Сайт проекта и демо</a>
+* <a href="http://ionden.com/a/plugins/ion.sound/ion.sound-1.0.0.zip">Скачать ion.sound-1.0.0.zip</a>
+
+***
+
+## Описание
+* Кроссбраузерная поддержка: Google Chrome, Mozilla Firefox, Opera, Safari, IE(9.0+) и мобильные браузеры
+* Плагин свободно распространяется на условиях <a href="http://ionden.com/a/plugins/licence.html" target="_blank">лицензии MIT</a>.
+* Ion.Sound включает в поставку 15 бесплатных звуковых файлов
+
+Сегодня веб-сайты переполнены событиями (новое письмо, новое сообщение в чат, обновление контента и т.п.). Часто не достаточно одной визуальной индикации этих событий, что бы привлечь внимание пользователя. Необходимы звуки! В этом деле вам поможет эта библиотека для воспроизведения коротких звуков.
+
+
+## Зависимости
+* <a href="http://jquery.com/" target="_blank">jQuery 1.9+</a>
+
+
+## Подключение
+Подключаем библиотеки:
+* jQuery
+* ion.sound.min.js
+
+Готовим звуковые файлы (15 звуков включены в поставку) и складываем их в какую-либо папку (например "sounds"):
+* my_cool_sound.mp3
+* my_cool_sound.ogg
+Помимо Mp3-файла, нужно так же подготовить Ogg-файл, так как не все браузеры поддерживают mp3. Конвертировать Mp3 в Ogg можно <a href="http://media.io/" target="_blank">прямо онлайн</a>.
+
+
+## Инициализация
+Инициализируем плагин:
+```javascript
+ion.sound.init();
+```
+
+Играем звук:
+```javascript
+ion.sound.play("my_cool_sound");
+```
+
+## Параметры
+<table class="options">
+    <thead>
+        <tr>
+            <th>Атрибут</th>
+            <th>По умолчанию</th>
+            <th>Описание</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>sounds</td>
+            <td>[Массив из 15 звуков]</td>
+            <td>Не обязательный параметр, позволяет задать набор подключаемых звуков</td>
+        </tr>
+        <tr>
+            <td>path</td>
+            <td>"static/sounds/"</td>
+            <td>Не обязательный параметр, указывает путь к папке со звуками</td>
+        </tr>
+        <tr>
+            <td>multiPlay</td>
+            <td>true</td>
+            <td>Не обязательный параметр, если указать <code>false</code>, то звуки не будут воспроизводиться одновременно</td>
+        </tr>
+        <tr>
+            <td>volume</td>
+            <td>0.5</td>
+            <td>Не обязательный параметр, задает базовую громкость от 0.0 до 1.0</td>
+        </tr>
+    </tbody>
+</table>
+
+Пример плагина подключенного с параметрами:
+```javascript
+ion.sound.init({
+    sounds: [                       // указываем названия звуков
+        "beer_can_opening",
+        "bell_ring",
+        "branch_break",
+        "button_click",
+        "button_click_on",
+        "button_push",
+        "button_tiny",
+        "camera_flashing",
+        "computer_error",
+        "door_bell",
+        "light_bulb_breaking",
+        "metal_plate",
+        "pop_cork",
+        "staple_gun",
+        "water_droplet"
+    ],
+    path: "sounds/",                // указываем папку где они лежат
+    multiPlay: false,               // запрещаем одновременное проигрывание
+    volume: "0.3"                   // делаем по тише
+});
+```
+
+Проигрываем один из звуков при нажатии на кнопку:
+```javascript
+$("#myButton").on("click", function(){
+    ion.sound.play("button_tiny");
+});
+```
+
+
+## История обновлений
+* 07.09.2013 - релиз плагина