sonorous

Sonorous.js

Sonorous.js เป็นไลบรารีเสียง JavaScript ที่ปรับปรุงการทำงานกับเสียงบนเว็บ ทำให้สามารถรวมเสียงเข้ากับเว็บแอปและเกมได้อย่างง่ายดาย ในฐานะที่เป็นนามธรรมเหนือ WebAudio API Sonorous.js นำเสนอการควบคุมอย่างละเอียดสำหรับผู้ที่ต้องการ ในขณะที่จัดการกับปัญหาข้ามเบราว์เซอร์ให้กับคุณ

โดยทีมงานจาก

สารบัญ

• ตัวอย่าง
• เริ่มต้นใช้งาน
  • การติดตั้งเสียงดัง
  • การใช้งาน
• เอพีไอ
  • เสียงดัง
  • โซนอร์
• การพัฒนาในท้องถิ่น
• มีส่วนร่วม
• เบราว์เซอร์ที่รองรับ

ตัวอย่าง

บูมบ็อกซ์

ติดตามมิกเซอร์

สตริงมาสเตอร์

ดูไดเร็กทอรี examples/ ของ repo สำหรับซอร์สโค้ด

เริ่มต้นใช้งาน

การติดตั้ง Sonorous.js

ในการเริ่มต้น ให้รัน npm install --save sonorous

หากต้องการใช้ Sonorous.js โปรดกำหนดให้ใช้หรือนำเข้าลงในไฟล์ของคุณ

อีเอส6

 import Sonorous from 'sonorous';

สามัญJS

 const Sonorous = require('sonorous');

การใช้งาน

Sonorous เป็นผู้จัดการที่จัดการการเพิ่มและการลบ Sonors โซเนอร์ถือได้ว่าเป็นเสื้อคลุมเหนือไฟล์เสียงหนึ่งไฟล์ Sonor แต่ละตัวมีฟังก์ชันการทำงานของตัวเอง เช่น play() , pause() , volume ฯลฯ คุณยังสามารถตั้งค่าคุณสมบัติส่วนกลาง ( masterVolume , muteAll ฯลฯ ) บน Sonor ทั้งหมดผ่านอินสแตนซ์ Sonorous

ตัวอย่าง:

 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

masterVolume : number

นี่เป็นคุณสมบัติการอ่าน/เขียนและเชื่อมต่อกับโหนด masterGain ซึ่งจะตั้งค่าระดับเสียงสำหรับออบเจ็กต์ Sonor ทั้งหมด ค่าที่ถูกต้องอยู่ระหว่าง 0 ถึง 1

muteAll : boolean

นี่คือคุณสมบัติการอ่าน/เขียนที่จะปิด/เปิดเสียงวัตถุ Sonor ทั้งหมด

วิธีการ

isSupported() -> boolean

คืนค่าเป็นจริงหากรองรับ WebAudio คืนค่าเป็นเท็จหากไม่รองรับ

addSonor (src ตัวเลือก) -> Sonor

สร้างวัตถุ Sonor และส่งคืนหากสำเร็จ

พารามิเตอร์	พิมพ์	คำอธิบาย
src	string , string[] , SonorSrc , SonorSrc[]	สื่อที่เกี่ยวข้องกับเสียงนี้ หากคุณส่งผ่านรูปแบบต่างๆ มากมาย มันจะเป็นรูปแบบแรกที่ใช้ได้กับเบราว์เซอร์ปัจจุบัน หาก URL แหล่งที่มาของคุณไม่มีส่วนขยาย คุณสามารถระบุได้ด้วยตนเองโดยใช้ออบเจ็กต์ SonorSrc ที่กำหนดไว้ด้านล่าง
ตัวเลือก	object	ออบเจ็กต์การกำหนดค่าเพิ่มเติม ดูตัวเลือกด้านล่าง

ตัวเลือกการกำหนดค่าสำหรับ addSonor() :

ตัวเลือก	พิมพ์	ค่าเริ่มต้น	คำอธิบาย
รหัส	string	สร้างขึ้นแบบสุ่ม	รหัสที่ไม่ซ้ำ หนึ่งจะถูกสร้างขึ้นสำหรับวัตถุนี้หากคุณไม่ผ่านหนึ่งรายการ
โหลดล่วงหน้า	boolean	true	จะพยายามโหลด URL โดยอัตโนมัติหากเป็นจริง หากเป็นเท็จ รหัสการโทรจะต้องเรียก load() อย่างชัดเจน
ปริมาณ	number	1.0	ระดับเสียงเริ่มต้น
วนซ้ำ	boolean	false	พิจารณาว่าเสียงควรวนซ้ำตลอดไปหรือไม่
เล่นอัตโนมัติ	boolean	false	พิจารณาว่าควรเล่นเสียงทันทีเมื่อมีการโหลดหรือไม่
ปิดเสียง	boolean	false	ปิดเสียงเมื่อโหลดแล้ว
ขนาดพูล	number	1	จำนวนเซ็กเมนต์เสียงทั้งหมดที่สามารถเล่นได้ การเพิ่มจำนวนนี้จะทำให้คุณสามารถเริ่มเล่นเสียงเดียวกันได้หลายครั้งพร้อมกัน ก่อนที่การเล่นครั้งแรกจะเสร็จสิ้น
ปรับให้เหมาะสมสำหรับ	string	'time'	อาจเป็น 'time' หรือ 'memory' ก็ได้ สิ่งนี้จะกำหนดว่าบัฟเฟอร์ที่ถอดรหัสจะถูกแคชหรือไม่ โดยค่าเริ่มต้นจะเป็น หากหน่วยความจำเป็นปัญหา ให้ตั้งค่านี้เป็น 'หน่วยความจำ' และคาดว่าจะเกิดความล่าช้าเล็กน้อยในขณะที่เราถอดรหัสบัฟเฟอร์ก่อนที่จะเริ่มเล่นได้

วัตถุ SonorSrc

คุณสมบัติ	พิมพ์	คำอธิบาย
URL	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'});

ลบ Sonor (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 ที่ตรงกับรหัสที่ส่งผ่าน

กิจกรรม

ปลดล็อคเสียงแล้ว

จะทริกเกอร์เมื่อเสียงถูกปลดล็อค (ผ่านการโต้ตอบของผู้ใช้กับเพจ) เบราว์เซอร์บางตัวไม่อนุญาตให้เล่นเสียงก่อนที่ผู้ใช้จะโต้ตอบกับเพจในทางใดทางหนึ่ง เหตุการณ์นี้จะเกิดขึ้นเมื่อเสียงมีอิสระในการเล่น

โซนอร์

โมดูลนี้ประกอบด้วยฟังก์ชันส่วนใหญ่ในการควบคุมเสียง รวมถึงการปรับระดับเสียง การเล่น การหยุดชั่วคราว ฯลฯ หากไม่ได้ปลดล็อค AudioContext (ผ่านท่าทางของผู้ใช้ ฯลฯ) การกระทำทั้งหมดจะเข้าสู่คิว การดำเนินการเหล่านี้จะดำเนินการทันทีทันทีที่ AudioContext ถูกปลดล็อคและโหลดบัฟเฟอร์แล้ว

คุณสมบัติ

id : string (อ่านอย่างเดียว)

คุณสมบัติอ่านอย่างเดียวที่ส่งกลับ ID เฉพาะสำหรับวัตถุเสียงนี้ คุณสามารถเลือกระบุรหัสได้ในระหว่างการเริ่มต้น (ดูข้อมูลเพิ่มเติมที่ addSonor() ของ Sonorous) หากไม่มีการระบุ ID ในระหว่างการเริ่มต้น สตริงตัวอักษรและตัวเลขที่สร้างขึ้นแบบสุ่มจะถูกกำหนดเป็น ID Sonorous สามารถดึงวัตถุ Sonor ได้ด้วย id โดยใช้ฟังก์ชัน Sonorous.get(id)

url : string (อ่านอย่างเดียว)

ส่งกลับ URL สำหรับเสียงต้นฉบับของวัตถุนี้

โหลดล่วงหน้า : boolean (อ่านอย่างเดียว)

คืนค่าเป็นจริงหากตั้งค่าโซเนอร์ให้โหลดล่วงหน้าระหว่างการเริ่มต้น

state : 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 (อ่านอย่างเดียว)

ส่งกลับระยะเวลาของโซเนอร์ โปรดทราบว่าค่านี้จะใช้ได้เฉพาะเมื่อโหลดโซเนอร์เท่านั้น หากไม่ได้โหลด sonor สิ่งนี้จะคืนค่า 0

isPlaying : boolean (อ่านอย่างเดียว)

คืนค่าเป็นจริงหากเสียงกำลังเล่นอยู่ คืนค่าเป็นเท็จหากไม่ใช่

ตำแหน่งการเล่น : number (อ่านอย่างเดียว)

คืนค่าระยะการเล่นเสียง หาก poolSize > 1 ระบบจะใช้ส่วนเสียงที่ใช้งานส่วนแรกเพื่อส่งคืนค่านี้

ขนาดสระ : number

คุณสมบัติสาธารณะแบบอ่าน/เขียนที่ควบคุมจำนวนส่วนของเสียงทั้งหมดในพูล เพิ่มขนาดของพูลหากคุณต้องการเริ่มเล่นเสียงเดียวกันไปพร้อมๆ กัน ค่าเริ่มต้นเป็น 1

เมื่อขนาดพูลเพิ่มขึ้น ตัวเซ็ตเตอร์/ตัวรับจะทำงานดังนี้: ตัวเซ็ตใดๆ จะถูกนำไปใช้กับเซ็กเมนต์ที่ใช้งานอยู่ทั้งหมด ผู้ทะเยอทะยานจะใช้ส่วนเสียงที่ใช้งานส่วนแรกเพื่อส่งคืนข้อมูลที่ร้องขอ ("เซ็กเมนต์ที่ใช้งานอยู่" คือเซ็กเมนต์ที่ถูกดึงออกจากพูลแล้ว และกำลังใช้งานอยู่)

ตัวอย่าง:

 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

หยุดชั่วคราว()

จะหยุดส่วนของเสียงที่ใช้งานอยู่ทั้งหมดชั่วคราว แต่จะไม่ส่งกลับไปยังพูล

หยุด()

จะหยุดส่วนเสียงที่ใช้งานอยู่ทั้งหมดและส่งกลับไปยังพูล

จางหายไป (ปริมาณเป้าหมาย, ระยะเวลาจาง, [เวลาเริ่มต้น])

จะทำให้เสียงจางลงจากโวลุ่มปัจจุบันไปยัง targetVolume ตามระยะเวลาเฟดที่ระบุ หากมีการระบุ startTime และมากกว่าเวลาปัจจุบันของ audioContext การจางจะเริ่มที่จุดนั้น มิฉะนั้นจะเริ่มทันที ระยะเวลาการจางควรอยู่ในรูปวินาที

แสวงหา (เวลาใหม่)

จะย้ายการเล่นตามเวลาที่ผ่านไปใน (หน่วยเป็นวินาที)

โหลด()

จะโหลดบัฟเฟอร์และเตรียมส่วนของเสียงสำหรับการเล่น

ยกเลิกการโหลด()

จะลบบัฟเฟอร์และส่งคืนส่วนเสียงที่ใช้งานอยู่ทั้งหมดไปยังพูล

บน (ชื่อเหตุการณ์, callbackFn)

วัตถุ Sonor เป็นตัวปล่อยเหตุการณ์ (เปิด/ปิด/ครั้งเดียว) ดูรายการกิจกรรมที่มีอยู่ด้านล่าง

ปิด (ชื่อเหตุการณ์, callbackFn)

ครั้งเดียว (ชื่อเหตุการณ์, โทรกลับ)

กิจกรรม

'โหลดแล้ว'

จะทริกเกอร์เมื่อมีการโหลดเสียง

พารามิเตอร์	พิมพ์	คำอธิบาย
โซนอร์อ็อบเจ	โซนอร์	ตัวอย่างของ Sonor ที่ถูกดำเนินการ

'เล่น'

จะทริกเกอร์เมื่อเริ่มเล่น

พารามิเตอร์	พิมพ์	คำอธิบาย
โซนอร์อ็อบเจ	โซนอร์	ตัวอย่างของ Sonor ที่ถูกดำเนินการ

'หยุดชั่วคราว'

จะทริกเกอร์เมื่อเสียงหยุดชั่วคราว

พารามิเตอร์	พิมพ์	คำอธิบาย
โซนอร์อ็อบเจ	โซนอร์	ตัวอย่างของ Sonor ที่ถูกดำเนินการ

'หยุด'

จะทริกเกอร์เมื่อเสียงหยุดเล่น

พารามิเตอร์	พิมพ์	คำอธิบาย
โซนอร์อ็อบเจ	โซนอร์	ตัวอย่างของ Sonor ที่ถูกดำเนินการ

'สิ้นสุด'

จะดังขึ้นเมื่อเสียงหมดระยะเวลา

พารามิเตอร์	พิมพ์	คำอธิบาย
โซนอร์อ็อบเจ	โซนอร์	ตัวอย่างของ Sonor ที่ถูกดำเนินการ

'แสวงหา'

จะทริกเกอร์เมื่อเวลาปัจจุบันมีการเปลี่ยนแปลงด้วยตนเอง

พารามิเตอร์	พิมพ์	คำอธิบาย
โซนอร์อ็อบเจ	โซนอร์	ตัวอย่างของ Sonor ที่ถูกดำเนินการ
แสวงหาตำแหน่ง	ตัวเลข	ไทม์โค้ดที่ Sonor แสวงหา

'ปริมาณการเปลี่ยนแปลง'

จะทริกเกอร์เมื่อระดับเสียงเปลี่ยนแปลง (ผ่านระดับเสียงหรือปิดเสียง)

พารามิเตอร์	พิมพ์	คำอธิบาย
โซนอร์อ็อบเจ	โซนอร์	ตัวอย่างของ Sonor ที่ถูกดำเนินการ
ใหม่ปริมาณ	ตัวเลข	ระดับเสียงใหม่ที่ Sonor ถูกตั้งค่าไว้

'อัตราการเล่นเปลี่ยนไป'

จะทริกเกอร์เมื่ออัตราการเล่นเปลี่ยนแปลง

พารามิเตอร์	พิมพ์	คำอธิบาย
โซนอร์อ็อบเจ	โซนอร์	ตัวอย่างของ Sonor ที่ถูกดำเนินการ
ใหม่อัตราการเล่น	ตัวเลข	อัตราการเล่นใหม่ที่ Sonor ถูกกำหนดไว้

'จางหายไป'

จะทริกเกอร์เมื่อการจางหายไปสิ้นสุดลง

พารามิเตอร์	พิมพ์	คำอธิบาย
โซนอร์อ็อบเจ	โซนอร์	ตัวอย่างของ Sonor ที่ถูกดำเนินการ

'ข้อผิดพลาด'

จะทริกเกอร์หากมีข้อผิดพลาดเกิดขึ้นระหว่างการทำงานของ Sonor

พารามิเตอร์	พิมพ์	คำอธิบาย
โซนอร์อ็อบเจ	โซนอร์	ตัวอย่างของ Sonor ที่ถูกดำเนินการ
ข้อผิดพลาด	สตริง	ข้อความแสดงข้อผิดพลาด

การพัฒนาในท้องถิ่น

เมื่อคุณมี repo ในเครื่องแล้ว ให้รัน yarn install เพื่อติดตั้งการขึ้นต่อกัน

• npm run build จะสร้าง Sonorous เวอร์ชันที่ไม่มีการลดทอน
• npm run build:production จะสร้าง Sonorous เวอร์ชันย่อขนาดและ gzip
• npm run start-dev จะสร้าง Sonorous ที่ไม่มีการลดทอน และเปิดหน้า html แบบง่ายพร้อมตัวควบคุมเสียง คุณสามารถทดสอบฟังก์ชัน Sonorous ส่วนใหญ่ได้ด้วยตนเองผ่านที่นั่น
• npm run test จะทำการทดสอบหน่วยทั้งหมด (การทดสอบหน่วยเขียนโดยใช้ Jest)

มีส่วนร่วม

เรายินดีรับฟังคำขอดึงและเสนอการเปลี่ยนแปลงฐานโค้ด โปรดทำตามขั้นตอนเหล่านี้เมื่อมีส่วนร่วม

1. โปรดแยกและแตกแขนงจาก develop และปฏิบัติตามคู่มือ Developing Locally เพื่อให้สามารถสร้างได้
2. แสดงความคิดเห็นโค้ดของคุณอย่างกว้างขวาง และอัปเดต README เมื่อคาดหวัง
3. เพิ่มการทดสอบหน่วยตามความเหมาะสม
4. ชุดการทดสอบที่มีอยู่ทั้งหมดจะต้องผ่าน และไม่ควรเกิดข้อผิดพลาดของ linder

เบราว์เซอร์ที่รองรับ

Sonorous ได้รับการสนับสนุนทุกที่ที่มี WebAudio คลิกที่นี่เพื่อดูรายการทั้งหมด