sonorous
v1.0.0
Sonorous.js é uma biblioteca de áudio JavaScript que agiliza o trabalho com áudio da web, permitindo fácil integração de áudio em aplicativos e jogos da web. Como uma abstração das APIs WebAudio, o Sonorous.js oferece controle refinado para quem precisa, enquanto lida com quaisquer problemas entre navegadores para você.
pela equipe de 
Caixa de som
Misturador de faixas
Mestre de cordas
Consulte o diretório examples/ do repositório para obter o código-fonte.
Para começar, execute npm install --save sonorous .
Para usar o Sonorous.js, solicite-o ou importe-o para o seu arquivo.
ES6
import Sonorous from 'sonorous';
CommonJS
const Sonorous = require('sonorous');
Sonorous é um gerenciador que cuida da adição e remoção de sons. Um sonor pode ser considerado um wrapper sobre um arquivo de áudio. Cada sonor tem sua própria funcionalidade, como play() , pause() , volume , etc. Você também pode definir propriedades globais ( masterVolume , muteAll , etc) em todos os sonoros por meio da instância Sonorous.
Exemplo:
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
Consulte a seção API para obter mais detalhes.
Sonorous é um singleton e irá gerenciar todos os objetos Sonor.
Sonor[] (somente leitura)Array de todos os objetos Sonor adicionados a este gerenciador.
AudioContext (somente leitura)Retorna o contexto de áudio atual usado pelo Sonorous.
numberEsta é uma propriedade de leitura/gravação e está conectada ao nó masterGain, que definirá o volume para todos os objetos Sonor. Os valores válidos estão entre 0 e 1.
booleanEsta é uma propriedade de leitura/gravação que irá ativar/desativar o som de todos os objetos Sonor.
booleanretorna verdadeiro se WebAudio for compatível, falso se não for.
Sonorcria um objeto Sonor e o retorna, se for bem-sucedido.
| Parâmetro | Tipo | Descrição |
|---|---|---|
| fonte | string , string[] , SonorSrc , SonorSrc[] | A mídia à qual este som está associado. Se você passar uma variedade de formatos diferentes, será necessário o primeiro que funcionar com o navegador atual. Se o seu URL de origem não tiver uma extensão, você pode especificá-la manualmente usando o objeto SonorSrc definido abaixo. |
| opções | object | Objeto de configuração opcional. Veja as opções abaixo. |
Opções de configuração para addSonor() :
| Opção | Tipo | Padrão | Descrição |
|---|---|---|---|
| eu ia | string | gerado aleatoriamente | Um ID exclusivo. Um será criado para este objeto se você não passar um. |
| pré-carregamento | boolean | true | Tentará carregar o URL automaticamente se for verdade. Se for falso, o código de chamada deverá chamar load() explicitamente. |
| volume | number | 1.0 | O volume inicial do som. |
| laço | boolean | false | Determine se o áudio deve ficar em loop para sempre. |
| reprodução automática | boolean | false | Determine se o áudio deve ser reproduzido imediatamente após o carregamento. |
| silenciado | boolean | false | Silenciar uma vez carregado. |
| tamanho da piscina | number | 1 | O número total de segmentos de áudio disponíveis para reprodução. Aumentar esse número permite que você comece a reproduzir simultaneamente o mesmo som várias vezes, antes que a reprodução inicial termine. |
| otimizarFor | string | 'time' | Pode ser 'time' ou 'memory' . Isto determina se o buffer decodificado será armazenado em cache ou não. Por padrão, será. Se a memória for uma preocupação, defina-a como 'memória' e espere um pequeno atraso enquanto decodificamos o buffer antes que a reprodução possa começar. |
| Propriedade | Tipo | Descrição |
|---|---|---|
| url | string | O URL de origem do áudio, sem extensão. |
| formatar | string | O formato especificado manualmente para esta fonte de áudio. |
Exemplo:
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'});
remove um objeto Sonor do gerenciador. Isso descarregará e destruirá o som e interromperá imediatamente todos os processos relacionados a esse som.
remove quaisquer objetos sonoros existentes e redefine o contexto de áudio.
destrói todos os objetos Sonor
Sonorretornar um objeto Sonor
Exemplo:
Sonorous.addSonor('./test_audio/test_sound_1.mp3', { id: 'mySonorId'});
let mySonor = Sonorous.get('mySonorId');
booleanretorne verdadeiro se Sonorous tiver um Sonor correspondente ao id passado
será acionado quando o áudio for desbloqueado (por meio da interação do usuário com a página). Alguns navegadores não permitem a reprodução de áudio antes que o usuário interaja de alguma forma com a página. Este evento será acionado quando o áudio estiver livre para reprodução.
Este módulo contém a maior parte da funcionalidade para controlar um som, incluindo ajuste de volume, reprodução, pausa, etc. Se o AudioContext não tiver sido desbloqueado (por meio de um gesto do usuário, etc.), todas as ações entrarão em uma fila. Essas ações serão executadas imediatamente assim que o AudioContext for desbloqueado e o buffer carregado.
string (somente leitura) Uma propriedade somente leitura que retorna o ID exclusivo desse objeto de som. O id é fornecido opcionalmente durante a inicialização (veja addSonor() do Sonorous para obter mais informações). Se nenhum ID for fornecido durante a inicialização, uma sequência alfanumérica gerada aleatoriamente será atribuída como o ID. Sonorous pode recuperar objetos Sonor por id, usando a função Sonorous.get(id) .
string (somente leitura)Retorna a URL do áudio de origem deste objeto.
boolean (somente leitura)Retorna verdadeiro se o sonor foi configurado para pré-carregar durante a inicialização.
string (somente leitura) Reflete o estado carregado do sonor. Pode ser 'loading' , 'loaded' ou 'unloaded' .
Exemplo:
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 (somente leitura)Retorna a duração do sonor. Observe que este valor só estará disponível quando um sonor for carregado. Se o sonor estiver descarregado, retornará 0.
boolean (somente leitura)Retorna verdadeiro se o som estiver sendo reproduzido no momento, falso se não estiver.
number (somente leitura)Retorna o quão avançado está a reprodução do som. Se poolSize > 1, o primeiro segmento de áudio ativo será usado para retornar esse valor.
numberUma propriedade pública de leitura/gravação que controla o número total de segmentos de áudio no pool. Aumente o tamanho do pool se quiser começar a reproduzir o mesmo som simultaneamente. O padrão é 1.
Depois que o tamanho do pool aumentar, os setters/getters se comportarão da seguinte forma: Qualquer setter será aplicado a todos os segmentos ativos. Qualquer getter usará o primeiro segmento de áudio ativo para retornar as informações solicitadas. (Um "segmento ativo" é aquele que já foi retirado do pool e está atualmente em uso.)
Exemplo:
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.
numberUma propriedade pública de leitura/gravação que controla a taxa de reprodução deste som. Se poolSize > 1, o primeiro segmento de áudio ativo será usado para retornar esse valor.
booleanUma propriedade pública de leitura/gravação que controla se o som fará loop ou não. Ao definir esta propriedade, ela será aplicada a todos os segmentos ativos.
numberUma propriedade pública de leitura/gravação que controla o volume deste som. Ao definir esta propriedade, ela será aplicada a todos os segmentos ativos.
booleanUma propriedade pública de leitura/gravação que controla se o som está silenciado ou não. Ao definir esta propriedade, ela será aplicada a todos os segmentos ativos.
reproduzirá a fonte de áudio. Se o sonor não tiver sido carregado, ele carregará o sonor e tocará uma vez carregado. Se o conjunto de segmentos de áudio for maior que 1, extraímos segmentos do conjunto conforme necessário. Um "segmento ativo" é aquele que já foi retirado do pool e está atualmente em uso. A lógica do jogo é a seguinte:
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
pausará todos os segmentos de áudio ativos, mas não os retornará ao pool.
interromperá todos os segmentos de áudio ativos e os retornará ao pool.
irá desvanecer o áudio do volume atual para o targetVolume, pela duração do desvanecimento fornecida. Se um startTime for fornecido e for maior que o horário atual do audioContext, o fade começará nesse ponto. Caso contrário, começará imediatamente. A duração do fade deve ser em segundos.
moverá a reprodução para o tempo decorrido (em segundos).
carregará o buffer e preparará um segmento de áudio para reprodução.
removerá o buffer e retornará todos os segmentos de áudio ativos ao pool.
O objeto Sonor é um emissor de eventos (ligado/desligado/uma vez). Veja abaixo a lista de eventos disponíveis.
Será acionado quando o som for carregado
| Parâmetro | Tipo | Descrição |
|---|---|---|
| sonorObj | Sonor | A instância do Sonor que foi operada |
Será acionado quando o jogo começar
| Parâmetro | Tipo | Descrição |
|---|---|---|
| sonorObj | Sonor | A instância do Sonor que foi operada |
Será acionado quando o som for pausado
| Parâmetro | Tipo | Descrição |
|---|---|---|
| sonorObj | Sonor | A instância do Sonor que foi operada |
Será acionado quando o som parar de tocar
| Parâmetro | Tipo | Descrição |
|---|---|---|
| sonorObj | Sonor | A instância do Sonor que foi operada |
Será acionado quando o som atingir o fim de sua duração
| Parâmetro | Tipo | Descrição |
|---|---|---|
| sonorObj | Sonor | A instância do Sonor que foi operada |
Será acionado quando o currentTime for alterado manualmente
| Parâmetro | Tipo | Descrição |
|---|---|---|
| sonorObj | Sonor | A instância do Sonor que foi operada |
| posição de busca | Número | Timecode que o Sonor procurou |
Será acionado quando o volume do som mudar (via volume ou mudo)
| Parâmetro | Tipo | Descrição |
|---|---|---|
| sonorObj | Sonor | A instância do Sonor que foi operada |
| novoVolume | Número | O novo volume que o Sonor foi configurado para |
Será acionado quando a taxa de reprodução mudar
| Parâmetro | Tipo | Descrição |
|---|---|---|
| sonorObj | Sonor | A instância do Sonor que foi operada |
| nova taxa de reprodução | Número | A nova taxa de reprodução para a qual o Sonor foi definido |
Será acionado quando o fade terminar
| Parâmetro | Tipo | Descrição |
|---|---|---|
| sonorObj | Sonor | A instância do Sonor que foi operada |
Será acionado se ocorrer algum erro durante uma operação do Sonor
| Parâmetro | Tipo | Descrição |
|---|---|---|
| sonorObj | Sonor | A instância do Sonor que foi operada |
| erro | Corda | Mensagem de erro |
Depois de ter o repositório localmente, execute yarn install para instalar as dependências.
npm run build irá construir versões não minificadas do Sonorous.npm run build:production irá construir versões reduzidas e compactadas do Sonorous.npm run start-dev criará o Sonorous não minificado e abrirá uma página HTML simples com controles de áudio. Você pode testar manualmente a maior parte da funcionalidade do Sonorous por lá.npm run test executará todos os testes de unidade. (Os testes unitários são escritos usando Jest)Aceitamos ativamente solicitações pull e alterações propostas na base de código. Siga estas etapas ao contribuir.
develop e siga o guia Desenvolvendo Localmente para poder ser construído.Sonorous é compatível onde quer que WebAudio esteja. Clique aqui para ver a lista completa.
