Packagecc.cote.metronome
Classpublic class Metronome
InheritanceMetronome Inheritance flash.events.EventDispatcher

The Metronome class plays a beep sound (optional) and dispatches events at regular intervals in a fashion similar to ActionScript's native Timer object. However, unlike the Timer class, the Metronome class is not affected by the runtime's frame rate. This makes it more precise and prevents the drifting problem that occurs over time with a Timer object.

At a moderate tempo, our tests show that the accuracy of the metronome is within ±0.03% which is comparable to off-the-shelf consumer electronic metronomes and much better than mechanical ones.

Using it is very simple. Simply instantiate it with the needed tempo and start it:

     var metro:Metronome = new Metronome(140);
     metro.start();

If you want to perform your own tasks when it ticks, listen to the MetronomeEvent.TICK event:

     var metro:Metronome = new Metronome(140);
     metro.addEventListener(MetronomeEvent.TICK, onTick);
     metro.start();
     
     public function onTick(e:MetronomeEvent):void {
         trace(e);
     }

If you want to use the Metronome more like a (more accurate) timer, you can define the interval in milliseconds (instead of BPMs), silence it and assign a predetermined number of ticks after which it should stop:

     var metro:Metronome = new Metronome();
     metro.interval = 1000;
     metro.volume = 0;
     metro.maxTickCount = 5;
     metro.addEventListener(MetronomeEvent.TICK, onTick);
     metro.addEventListener(MetronomeEvent.STOP, onTick);
     metro.start();
     
     public function onTick(e:MetronomeEvent):void {
         trace(e);
     }

The extraPrecise property

By default, the extraPrecise property of the Metronome is set to false. This should be fine in all but the most demanding cases. If you do need a little extra accuracy, beware that the CPU usage will be higher.

The other edge case where you would need to set the extraPrecise property to true is if you want to use a BPM that is lower than 12 beats per seconds (or an interval that is longer than 5000 milliseconds).

Using in Flash Pro

This library uses sound assets embedded with the [Embed] instruction. This will work fine in FlashBuilder (and tools that use a similar compiler) but might give you problems in Flash Pro. If you are using Flash Pro, you should simply link the Metronome.swc file to avoid any issues.

Requirements

Because it uses the SampleDataEvent class of the Sound API, the Metronome class only works in Flash Player 10+ and AIR 1.5+.

See also

cc.cote.metronome.MetronomeEvent
http://cote.cc/projects/metronome
http://github.com/cotejp/Metronome


Public Properties
 PropertyDefined By
  accentedBeep : Sound
The beeping sound that plays for 'accented' beats.
Metronome
  accentedBeepVolume : Number
The volume of the metronome's accented beep sound expressed as a number between 0 (minimum volume) and 1 (maximum volume).
Metronome
  extraPrecise : Boolean
Indicates whether the extraPrecise mode is being used.
Metronome
  interval : uint
The interval (in milliseconds) between ticks.
Metronome
  maxTickCount : uint
The maximum number of times the Metronome should tick.
Metronome
  missed : uint
[read-only] The number of times, since the metronome was started, that it couldn't properly schedule a tick.
Metronome
  pattern : Array
This array defines the beeps that will be accented by the metronome.
Metronome
  regularBeep : Sound
The beeping sound that plays for 'normal' beats.
Metronome
  regularBeepVolume : Number
The volume of the metronome's regular beep sound expressed as a number between 0 (minimum volume) and 1 (maximum volume).
Metronome
  running : Boolean
[read-only] Indicates whether the metronome is currently running.
Metronome
  startTime : Number
[read-only] The time when the metronome was last started expressed as the number of milliseconds elapsed since midnight on January 1st, 1970, universal time.
Metronome
  tempo : Number
The current tempo of the metronome in beats per minute.
Metronome
  ticks : uint
[read-only] The number of times the metronome ticked.
Metronome
  volume : Number
The overall volume of the metronome's beep sounds expressed as a number between 0 (minimum volume) and 1 (maximum volume).
Metronome
Public Methods
 MethodDefined By
  
Metronome(tempo:uint = 120, volume:Number = 1.0, pattern:Array = null, maxTickCount:uint = 0)
Constructs a new Metronome object, pre-set at the desired tempo and volume.
Metronome
  
start():void
Starts the metronome.
Metronome
  
stop():void
Stops the metronome.
Metronome
Events
 Event Summary Defined By
  Dispatched when the metronome starts.Metronome
  Dispatched when the metronome stops.Metronome
  Dispatched each time the metronome ticks.Metronome
Public Constants
 ConstantDefined By
  SAMPLE_RATE : uint = 44100
[static] The maximum sound sample rate available in ActionScript (in Hertz).
Metronome
  VERSION : String = 1.0b rev1
[static] Version string of this release
Metronome
Property Detail
accentedBeepproperty
accentedBeep:Sound

The beeping sound that plays for 'accented' beats. An 'accented' beat is one that falls on beats divisible by the base property. If you decide to use you own sound, its duration should be shorter than the interval between two beats.


Implementation
    public function get accentedBeep():Sound
    public function set accentedBeep(value:Sound):void
accentedBeepVolumeproperty 
accentedBeepVolume:Number

The volume of the metronome's accented beep sound expressed as a number between 0 (minimum volume) and 1 (maximum volume).


Implementation
    public function get accentedBeepVolume():Number
    public function set accentedBeepVolume(value:Number):void
extraPreciseproperty 
extraPrecise:Boolean

Indicates whether the extraPrecise mode is being used. By default, it is not. When activated, the metronome gains a little more precision. However, extraPrecise mode consumes more CPU cycles. Unless you really need the extra accuracy, you should leave it to false.


Implementation
    public function get extraPrecise():Boolean
    public function set extraPrecise(value:Boolean):void

Throws
IllegalOperationError — The 'extraPecise' mode cannot be changed while the Metronome is running
intervalproperty 
interval:uint

The interval (in milliseconds) between ticks. Modifying this value alters the tempo just as modifying the tempo alters the interval between ticks. The interval must be at least 100 milliseconds and at most 5000 milliseconds. If extraPrecise is set to true, the interval can be as long as wanted.


Implementation
    public function get interval():uint
    public function set interval(value:uint):void

Throws
ArgumentError — The interval must be at least 100 milliseconds long.
 
ArgumentError — To use an interval longer than 5000 milliseconds, you must set "extraPrecise" to true.
maxTickCountproperty 
maxTickCount:uint

The maximum number of times the Metronome should tick. A value of 0 means no maximum.


Implementation
    public function get maxTickCount():uint
    public function set maxTickCount(value:uint):void
missedproperty 
missed:uint  [read-only]

The number of times, since the metronome was started, that it couldn't properly schedule a tick. This is typically caused by the processor being overloaded during one or a few frames. If you get misses, make sure each frame's code is processed within the time it has been allocated.

For example, if you are running your application at 30 frames per second, each frame has 33.3 milliseconds to complete its tasks. If it takes more than that, all processing occuring after will be pushed back. In some instances (depending on frame rate and metronome tempo), this could mean the processing of the Metronome events will be pushed so far back that it will actually occur after a TICK should have been dispatched. If this happens, the metronome will fire two or more TICKs back-to-back in order to stay in line with the tempo.

Obviously, this is not desirable. The solution is to adjust your code so it stays within its allocated frame time (budget). You can verify that by using a tool such as Adobe Scout.


Implementation
    public function get missed():uint
patternproperty 
pattern:Array

This array defines the beeps that will be accented by the metronome. Each entry in the array is a boolean value. A 'true' value means the beep will be accented and a value of 'false' means it will not.


Implementation
    public function get pattern():Array
    public function set pattern(value:Array):void
regularBeepproperty 
regularBeep:Sound

The beeping sound that plays for 'normal' beats. A 'normal' beat is one that falls on beats not divisible by the base property. If you decide to use your own sound, its duration should be shorter than the interval between two beats.


Implementation
    public function get regularBeep():Sound
    public function set regularBeep(value:Sound):void
regularBeepVolumeproperty 
regularBeepVolume:Number

The volume of the metronome's regular beep sound expressed as a number between 0 (minimum volume) and 1 (maximum volume).


Implementation
    public function get regularBeepVolume():Number
    public function set regularBeepVolume(value:Number):void
runningproperty 
running:Boolean  [read-only]

Indicates whether the metronome is currently running.


Implementation
    public function get running():Boolean
startTimeproperty 
startTime:Number  [read-only]

The time when the metronome was last started expressed as the number of milliseconds elapsed since midnight on January 1st, 1970, universal time.


Implementation
    public function get startTime():Number
tempoproperty 
tempo:Number

The current tempo of the metronome in beats per minute. The tempo must be 12 or greater and less than 600 beats per minute. If the extraPrecise property is set to true, you can define a tempo lower than 12. It can even be a fractional number, as long as its larger than 0.


Implementation
    public function get tempo():Number
    public function set tempo(value:Number):void

Throws
ArgumentError — The tempo must be greater than 0 and less than 600 beats per minute.
 
ArgumentError — To use a tempo slower than 12 BPM, you must set "extraPrecise" to true.
ticksproperty 
ticks:uint  [read-only]

The number of times the metronome ticked. This number is reset on start but not on stop. This means you can retrieve the number of times it ticked even after it was stopped.


Implementation
    public function get ticks():uint
volumeproperty 
volume:Number

The overall volume of the metronome's beep sounds expressed as a number between 0 (minimum volume) and 1 (maximum volume). When set, it defines the volume of both the regular beep sound and the accented beep sound. If you want to control them individually, use the regularBeepVolume and accentedBeepVolume properties.


Implementation
    public function get volume():Number
    public function set volume(value:Number):void
Constructor Detail
Metronome()Constructor
public function Metronome(tempo:uint = 120, volume:Number = 1.0, pattern:Array = null, maxTickCount:uint = 0)

Constructs a new Metronome object, pre-set at the desired tempo and volume.

Parameters
tempo:uint (default = 120) — The tempo to set the Metronome to (can be altered anytime with the 'tempo' property).
 
volume:Number (default = 1.0) — The volume of the beep sounds.
 
pattern:Array (default = null) — This array tells the metronome when it should play the accented beep sound instead of the regular beep sound. See the documentation of the pattern property for more details. By default an empty array is used meaning no beeps will be accented.
 
maxTickCount:uint (default = 0) — The maximum number ot ticks to trigger. The default (0) means no maximum.
Method Detail
start()method
public function start():void

Starts the metronome. MetronomeEvent.TICK will be dispatched each time the Metronome ticks. Beeps will sound if the silent property is false.

stop()method 
public function stop():void

Stops the metronome.

Event Detail
start Event
Event Object Type: cc.cote.metronome.MetronomeEvent
MetronomeEvent.type property = cc.cote.metronome.MetronomeEvent.START

Dispatched when the metronome starts.

The START constant defines the value of the type property of a start event object.
stop Event  
Event Object Type: cc.cote.metronome.MetronomeEvent
MetronomeEvent.type property = cc.cote.metronome.MetronomeEvent.STOP

Dispatched when the metronome stops.

The STOP constant defines the value of the STOP property of a STOP event object.
tick Event  
Event Object Type: cc.cote.metronome.MetronomeEvent
MetronomeEvent.type property = cc.cote.metronome.MetronomeEvent.TICK

Dispatched each time the metronome ticks.

The TICK constant defines the value of the type property of a tick event object.
Constant Detail
SAMPLE_RATEConstant
public static const SAMPLE_RATE:uint = 44100

The maximum sound sample rate available in ActionScript (in Hertz).

VERSIONConstant 
public static const VERSION:String = 1.0b rev1

Version string of this release