Dancer.js 高品质音频 JavaScript API 插件

Question

Dancer.js 是一个高级的音频 API，旨在创建炫酷的可视化效果，可以和 Mozilla 的 Audio Data API 以及 Webkit 的 Web Audio API 结合使用，可以为你设计出一套可视化网络音频 API。

特点

• 使用实时音频波形和频率数据，并可映射为各种可视化效果
• 从现有的音频源中获取音频数据
• 可检测到你的可视化效果
• 支持Web Audio（webkit）、Audio Data（mozilla）和flash fallback（v9+）
• 可扩展，支持插件和自定义行为

实例方法

Setup

• load( source ) specifies the audio source for the dancer instance. source can either be an audio element, or an object with a src property and an optional codecs array. While the audio element source is recommended to use with other players, if you specify a config object, the src property can either be a string of the audio path, or a string of the audio path, without the file extension, if you specify a codec array to work across multiple audio implementations. Examples of input:

  var dancer = new Dancer();

  // Using an audio object
  var a = new Audio();
  a.src = 'somesong.mp3';
  dancer.load( a );

  // Using an audio element on the page
  dancer.load( document.getElementsByTagName('audio')[0] );

  // Using a config object and you only have one encoding
  dancer.load({ src: 'somesong.mp3' });

  // Using a config object, and you have an ogg and mp3 version
  dancer.load({ src: 'somesong', codecs: [ 'ogg', 'mp3' ]});

Controls

All controls return this. If provided an audio element as the source, one can also control the audio through that, or can access the audio element in the audio property on the dancer instance.

• play() plays the audio and begins the dance.
• pause() pauses the madness.
• setVolume() sets the player's current volume.

Getters

• getVolume() returns a normalized value (0 to 1) of the current volume.
• getTime() returns the current time.
• getProgress() returns the downloading progress as a float from 0 to 1.
• getWaveform() returns the waveform data array (Float32Array(1024))
• getSpectrum() returns the frequency data array (Float32Array(512)).
• getFrequency( freq [, endFreq ] ) returns the magnitude of a frequency or average over a range of frequencies.
• isLoaded() returns a boolean value for the dancer instance's song load state.
• isPlaying() returns a boolean value indicating whether the dancer instance's song is currently playing or not.

Sections

All section methods return this (CHAIN IT UP) and callbacks executed with this referencing the dancer instance.

• after( t, callback ) fires callback on every frame after time t.
• before( t, callback ) fires callback on every frame before time t.
• between( t0, t1, callback ) fires callback on every frame between time t0 and t1.
• onceAt( t, callback ) fires callback once at time t.

Bindings

Basic pub/sub to tie into the dancer instance. update and loaded are predefined events called within the framework that are published on every frame (update) and on audio file load (loaded). All callbacks executed with this referencing the dancer instance.

• bind( name, callback ) subscribes a callback of name. Can call this method several times to bind several callbacks of the same name.
• unbind( name ) unsubscribes all callbacks of name.
• trigger( name ) calls all callbacks of name.

Kick

Kicks are detected when the amplitude (normalized values between 0 and 1) of a specified frequency, or the max amplitude over a range, is greater than the minimum threshold, as well as greater than the previously registered kick's amplitude, which is decreased by the decay rate per frame.

• createKick( options ) creates a new kick instance tied to the dancer instance, with an options object passed as an argument. Options listed below.
  • frequency the frequency (element of the spectrum) to check for a spike. Can be a single frequency (number) or a range (2 element array) that uses the frequency with highest amplitude. Default: [ 0, 10 ]
  • threshold the minimum amplitude of the frequency range in order for a kick to occur. Default: 0.3
  • decay the rate that the previously registered kick's amplitude is reduced by on every frame. Default: 0.02
  • onKick the callback to be called when a kick is detected.
  • offKick the callback to be called when there is no kick on the current frame.

静态方法

• addPlugin( name, fn ) registers a plugin of name with initiation function fn -- described in more detail below
• isSupported() returns a string of webaudio, audiodata or flash indicating level of support. Returns an empty string if the browser doesn't support any of the methods. Can also return null when browser does not support typed arrays.
• canPlay( type ) returns either true or false indicating whether the browser supports playing back audio of type type, which can be a string of 'mp3', 'ogg', 'wav', or 'aac'.
• setOptions( options ) takes a set of key-value pairs in an object for options. Options below.
• version not a method, but a property of the Dancer object to return a string of the current Dancer version

Dancer Options

• flashSWF The path to soundmanager2.swf. Required for flash fallback.
• flashJS The path to soundmanager2.js. Required for flash fallback.

Kick实例方法

These methods can be called on a kick instance to turn on and off the registered callbacks

• on() turns on the kick instance's callbacks and detections
• off() turns off the kick instance's callbacks and detections
• set( options ) can pass in an object literal with the 5 kick options, similar to creating a new kick option

使用示例

For simple examples, check out the examples/ folder -- both the FFT and waveform examples are straight forward, leveraging the corresponding plugins for visualizations.

  // To enable flash fallback, specify the paths for the flashSWF and flashJS
  Dancer.setOptions({
    flashJS  : '../../lib/soundmanager2.js',
    flashSWF : '../../lib/soundmanager2.swf'
  });

  var
    audio  = document.getElementsByTagName('audio')[0],
    dancer = new Dancer(),
    kick = dancer.createKick({
      onKick: function ( mag ) {
        console.log('Kick!');
      },
      offKick: function ( mag ) {
        console.log('no kick :(');
      }
    });

  // Let's turn this kick on right away
  kick.on();

  dancer.onceAt( 10, function() {
    // Let's set up some things once at 10 seconds
  }).between( 10, 60, function() {
    // After 10s, let's do something on every frame for the first minute
  }).after( 60, function() {
    // After 60s, let's get this real and map a frequency to an object's y position
    // Note that the instance of dancer is bound to "this"
    object.y = this.getFrequency( 400 );
  }).onceAt( 120, function() {
    // After 120s, we'll turn the kick off as another object's y position is still being mapped from the previous "after" method
    kick.off();
  }).load( audio ); // And finally, lets pass in our Audio element to load

  dancer.play();

依赖关系

HTML5 Playback with Web Audio or Audio Data Chrome and Firefox are both supported out of the box -- other browsers will need to leverage the flash fallback until either of these APIs are implemented.

Safari 6 Web Audio API While Safari 6 does have the Web Audio API, it doesn't currently support processing audio from a media element source. Falls back to flash.

To enable flash You must set Dancer's defaults for flashSWF with the path to the soundmanager2.swf and flashJS to the path to soundmanager2.js, both found in lib/. Flash player 9 is required, and you must provide an mp3 option. Waveform data in Flash is a 1024 Float32Array, but only the first 512 elements have values due to flash's computeSpectrum method.

Uint32Array and Float32Array are required Include a shim if you'd like to support browsers that do not have these typed arrays.

相关连接

Github 地址：https://github.com/jsantell/dancer.js