Package | cc.cote.metronome |
Class | public class Metronome |
Inheritance | Metronome ![]() |
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
Property | Defined 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 |
Method | Defined 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 |
Event | Summary | Defined By | ||
---|---|---|---|---|
Dispatched when the metronome starts. | Metronome | |||
Dispatched when the metronome stops. | Metronome | |||
Dispatched each time the metronome ticks. | Metronome |
Constant | Defined 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 |
accentedBeep | property |
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.
public function get accentedBeep():Sound
public function set accentedBeep(value:Sound):void
accentedBeepVolume | property |
accentedBeepVolume:Number
The volume of the metronome's accented beep sound expressed as a number between 0 (minimum volume) and 1 (maximum volume).
public function get accentedBeepVolume():Number
public function set accentedBeepVolume(value:Number):void
extraPrecise | property |
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.
public function get extraPrecise():Boolean
public function set extraPrecise(value:Boolean):void
IllegalOperationError — The 'extraPecise' mode cannot be changed while the
Metronome is running
|
interval | property |
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.
public function get interval():uint
public function set interval(value:uint):void
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.
|
maxTickCount | property |
maxTickCount:uint
The maximum number of times the Metronome should tick. A value of 0 means no maximum.
public function get maxTickCount():uint
public function set maxTickCount(value:uint):void
missed | property |
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.
public function get missed():uint
pattern | property |
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.
public function get pattern():Array
public function set pattern(value:Array):void
regularBeep | property |
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.
public function get regularBeep():Sound
public function set regularBeep(value:Sound):void
regularBeepVolume | property |
regularBeepVolume:Number
The volume of the metronome's regular beep sound expressed as a number between 0 (minimum volume) and 1 (maximum volume).
public function get regularBeepVolume():Number
public function set regularBeepVolume(value:Number):void
running | property |
running:Boolean
[read-only] Indicates whether the metronome is currently running.
public function get running():Boolean
startTime | property |
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.
public function get startTime():Number
tempo | property |
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.
public function get tempo():Number
public function set tempo(value:Number):void
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.
|
ticks | property |
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.
public function get ticks():uint
volume | property |
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.
public function get volume():Number
public function set volume(value:Number):void
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.
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.
|
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.
start | Event |
cc.cote.metronome.MetronomeEvent
cc.cote.metronome.MetronomeEvent.START
Dispatched when the metronome starts.
TheSTART
constant defines the value of the type
property of a
start
event object.
stop | Event |
cc.cote.metronome.MetronomeEvent
cc.cote.metronome.MetronomeEvent.STOP
Dispatched when the metronome stops.
TheSTOP
constant defines the value of the STOP
property of a
STOP
event object.
tick | Event |
cc.cote.metronome.MetronomeEvent
cc.cote.metronome.MetronomeEvent.TICK
Dispatched each time the metronome ticks.
TheTICK
constant defines the value of the type
property of a
tick
event object.
SAMPLE_RATE | Constant |
public static const SAMPLE_RATE:uint = 44100
The maximum sound sample rate available in ActionScript (in Hertz).
VERSION | Constant |
public static const VERSION:String = 1.0b rev1
Version string of this release