sonorous

鏗鏘.js

Sonorous.js 是一個 JavaScript 音訊庫，可簡化 Web 音訊的處理，使音訊能夠輕鬆整合到 Web 應用程式和遊戲中。作為 WebAudio API 的抽象，Sonorous.js 為需要的人提供細粒度的控制，同時為您處理任何跨瀏覽器問題。

由團隊從

目錄

• 範例
• 入門
  • 安裝鏗鏘有力
  • 用法
• 應用程式介面
  • 鏗鏘有力
  • 索諾爾
• 本土化發展
• 貢獻
• 支援的瀏覽器

範例

音箱

軌道混音器

弦樂大師

請參閱儲存庫的examples/目錄以取得原始程式碼。

入門

安裝 Sonorous.js

首先，執行npm install --save sonorous 。

要使用 Sonorous.js，需要它或將其匯入到您的檔案中。

ES6

 import Sonorous from 'sonorous';

CommonJS

 const Sonorous = require('sonorous');

用法

Sonorous 是一個管理器，負責處理聲納的新增和刪除。聲納可以被認為是一個音訊檔案的包裝。每個muteAll都有自己的功能，例如play() 、 masterVolume pause() 、 volume等。

例子：

 let mySonor = Sonorous.addSonor('./test_audio/test_sound_1.mp3');
mySonor.play(); // begins to play test_sound_1.mp3
mySonor.volume = 0.5; // sets the volume of the sonor to 0.5
Sonorous.muteAll = true; // mutes all sonors
mySonor.stop(); // stops the playback of test_sound_1.mp3

請參閱 API 部分以了解更多詳細資訊。

應用程式介面

鏗鏘有力

Sonorous 是一個單例，將管理所有 Sonor 物件。

特性

sonors : Sonor[] （唯讀）

新增至此管理員的所有 Sonor 物件的陣列。

ctx ： AudioContext （唯讀）

返回 Sonorous 使用的目前音訊上下文。

主卷： number

這是一個讀/寫屬性，連接到 masterGain 節點，該節點將為所有 Sonor 物件設定音量。有效值介於 0 和 1 之間。

全部靜音： boolean

這是一個讀取/寫入屬性，可將所有 Sonor 物件靜音/取消靜音。

方法

isSupported() -> boolean

如果支援 WebAudio，則傳回 true；如果不支持，則傳回 false。

addSonor(src, 選項) -> Sonor

建立一個 Sonor 物件並傳回它（如果成功）。

參數	類型	描述
原始碼	string , string[] , SonorSrc , SonorSrc[]	該聲音關聯的媒體。如果您傳入各種格式的數組，它將採用第一個適用於目前瀏覽器的格式。如果您的來源 url 沒有副檔名，您可以使用下方定義的 SonorSrc 物件手動指定。
選項	object	可選配置對象。請參閱下面的選項。

addSonor()的設定選項：

選項	類型	預設	描述
ID	string	隨機產生的	唯一的 ID。如果您不傳入一個對象，則會為此對象建立一個。
預載	boolean	true	如果為 true，將嘗試自動載入 url。如果為 false，則呼叫程式碼必須明確呼叫load() 。
體積	number	1.0	聲音的初始音量。
環形	boolean	false	確定音訊是否應永遠循環。
自動播放	boolean	false	確定音訊是否應在載入時立即播放。
靜音	boolean	false	載入後靜音。
池大小	number	1	可播放的音訊片段總數。增加此數字可以讓您在初始播放完成之前開始多次同時播放相同的聲音。
最佳化	string	'time'	可以是'time'或'memory' 。這決定了解碼後的緩衝區是否會被快取。預設情況下，會的。如果記憶體是一個問題，那麼將其設為“記憶體”，並在開始播放之前解碼緩衝區時預計會有一點延遲。

SonorSrc 對象

財產	類型	描述
網址	string	音訊的來源 URL，不含副檔名。
格式	string	為此音訊來源手動指定的格式。

例子：

 let mySonor = Sonorous.addSonor('./test_audio/test_sound_1.mp3', {
    id: 'myFirstSonor', 
    preload: false,
    volume: 0.5,
    poolSize: 3 });

let testSoundSonor = Sonorous.addSonor(
    {
        url: './test_audio/test_sound_2',
        format: 'mp3'
    }, 
    { id: 'test_sound_2'});

刪除聲納（id）

從管理員中刪除 Sonor 物件。這將卸載並銷毀聲音，並立即停止與該聲音相關的所有進程。

重新載入()

刪除任何現有的聲納物件並重置音訊上下文。

卸下（）

銷毀所有 Sonor 對象

取得（id）-> Sonor

傳回 Sonor 對象

例子：

 Sonorous.addSonor('./test_audio/test_sound_1.mp3', { id: 'mySonorId'});
let mySonor = Sonorous.get('mySonorId');

有(id) -> boolean

如果 Sonorous 有一個 Sonor 與傳入的 id 匹配，則傳回 true

活動

音訊解鎖

當音訊解鎖時（透過使用者與頁面的互動）將觸發。某些瀏覽器不允許在使用者以某種方式與頁面互動之前播放音訊。一旦音訊可以自由播放，此事件就會觸發。

索諾爾

此模組包含控制聲音的大部分功能，包括調整音量、播放、暫停等。一旦 AudioContext 解鎖並且緩衝區已加載，這些操作將立即執行。

特性

id : string （唯讀）

一個唯讀屬性，傳回該聲音物件的唯一 ID。 id 可以在初始化期間選擇性地提供（有關更多信息，請參閱 Sonorous 的 addSonor()）。如果在初始化期間未提供 ID，則會將隨機產生的字母數字字串指定為 id。 Sonorous 可以使用Sonorous.get(id)函數透過 id 擷取 Sonor 物件。

url : string （唯讀）

傳回該物件的來源音訊的 url。

預先載入： boolean （唯讀）

如果聲納在初始化期間設定為預先加載，則傳回 true。

狀態： string （唯讀）

反映聲納的負載狀態。可以是'loading' 、 'loaded'或'unloaded' 。

例子：

 let mySonor = Sonorous.addSonor('./test_audio/test_sound_1.mp3', { preload: false });
console.log(mySonor.state); // prints out 'unloaded'

mySonor.load();
console.log(mySonor.state); // prints out 'loading'

持續時間： number （唯讀）

返回聲納的持續時間。請注意，該值僅在載入聲納時才可用。如果聲納已卸載，則傳回 0。

isPlaying : boolean （唯讀）

如果目前正在播放聲音，則傳回 true，否則傳回 false。

playbackPosition : number （唯讀）

返回聲音播放的進度。如果 poolSize > 1，則將使用第一個活動音訊片段來傳回該值。

池大小： number

控制池中音訊段總數的讀取/寫入公共屬性。如果您想開始同時播放相同的聲音，請增加池的大小。預設為 1。

一旦池大小增加，setter/getter 將表現如下： 任何 setter 都會應用於所有活動段。任何獲取器都將使用第一個活動音訊段來傳回所要求的資訊。 （「活動段」是指已從池中提取且目前正在使用的段。）

例子：

 let mySonor = Sonorous.addSonor('./test_audio/test_sound_1.mp3');
mySonor.poolSize = 2;
mySonor.play();
setTimeout(() => { mySonor.play(); }, 1000);  // will result in the same audio being played twice, with the second playback 1s behind the first one.

播放速率： number

控制該聲音的播放速率的讀取/寫入公共屬性。如果 poolSize > 1，則將使用第一個活動音訊片段來傳回該值。

循環： boolean

控制聲音是否循環的讀取/寫入公共屬性。設定此屬性時，它將套用於所有活動段。

體積 : number

控制該聲音音量的讀取/寫入公共屬性。設定此屬性時，它將套用於所有活動段。

靜音： boolean

控制聲音是否靜音的讀取/寫入公共屬性。設定此屬性時，它將套用於所有活動段。

方法

玩（）

將播放音訊來源。如果尚未加載聲納，它將加載聲納並在加載後播放。如果音訊片段池大於 1，則我們根據需要從池中提取片段。 「活動段」是已經從池中拉出並且目前正在使用的段。播放邏輯如下：

 if there are no active segments:
    retrieve one from the pool and play it.

if there are active segments:
    if none are currently playing:
        play all active segments
    else:
        retrieve/play a segment from the pool

if there are no available segments in the pool:
    do nothing and report an error

暫停（）

將暫停所有活動的音訊片段，但不會將它們返回池中。

停止（）

將停止所有活動的音訊片段並將它們返回池中。

淡入淡出（目標音量，淡入淡出持續時間，[開始時間]）

在提供的淡入淡出持續時間內，將音訊從目前音量淡入目標音量。如果提供了 startTime 並且大於 audioContext 的當前時間，則淡入淡出將從該點開始。否則，它將立即開始。淡入淡出持續時間應以秒為單位。

尋找（新時間）

會將播放移至傳入的時間（以秒為單位）。

載入()

將加載緩衝區並準備播放音訊片段。

卸下（）

將刪除緩衝區並將所有活動音訊片段返回池中。

on(事件名稱, 回呼Fn)

Sonor 物件是一個事件發射器（開/關/一次）。請參閱下面的可用事件清單。

關閉（事件名稱，callbackFn）

一次（事件名稱，回呼）

活動

“已載入”

聲音載入時觸發

參數	類型	描述
聲納對象	索諾爾	進行操作的 Sonor 實例

'玩'

播放開始時觸發

參數	類型	描述
聲納對象	索諾爾	進行操作的 Sonor 實例

'暫停'

當聲音暫停時觸發

參數	類型	描述
聲納對象	索諾爾	進行操作的 Sonor 實例

'停止'

當聲音停止播放時觸發

參數	類型	描述
聲納對象	索諾爾	進行操作的 Sonor 實例

‘結束’

當聲音到達其持續時間結束時將觸發

參數	類型	描述
聲納對象	索諾爾	進行操作的 Sonor 實例

‘尋求’

當手動更改 currentTime 時將觸發

參數	類型	描述
聲納對象	索諾爾	進行操作的 Sonor 實例
尋找位置	數位	Sonor 尋求的時間碼

‘音量改變’

當音量變化時觸發（透過音量或靜音）

參數	類型	描述
聲納對象	索諾爾	進行操作的 Sonor 實例
新卷	數位	Sonor 設定的新音量

'播放速率已更改'

當播放速率改變時會觸發

參數	類型	描述
聲納對象	索諾爾	進行操作的 Sonor 實例
新的播放速率	數位	Sonor 設定的新播放速率

'褪色完成'

當淡入淡出結束時觸發

參數	類型	描述
聲納對象	索諾爾	進行操作的 Sonor 實例

'錯誤'

如果 Sonor 操作期間發生任何錯誤，將會觸發

參數	類型	描述
聲納對象	索諾爾	進行操作的 Sonor 實例
錯誤	細繩	錯誤訊息

本土化發展

本地擁有儲存庫後，執行yarn install來安裝依賴項。

• npm run build將建構 Sonorous 的未縮小版本。
• npm run build:production將建構 Sonorous 的縮小版和壓縮版。
• npm run start-dev將建立未縮小的 Sonorous 並開啟一個帶有音訊控制的簡單 html 頁面。您可以透過那裡手動測試大部分 Sonorous 功能。
• npm run test將執行所有單元測試。 （單元測試是使用 Jest 編寫的）

貢獻

我們積極歡迎拉取請求和對程式碼庫的擬議變更。貢獻時請遵循以下步驟。

1. 請從develop中分叉和分支，並按照本地開發指南來建立。
2. 廣泛註釋您的程式碼，並在需要時更新自述文件。
3. 在適用的情況下新增單元測試。
4. 所有現有的測試套件都必須通過，且不應出現 linter 錯誤。

支援的瀏覽器

只要有 WebAudio，就支援 Sonorous。按一下此處查看完整列表。