Conductor

The Conductor class is a core singleton that manages musical timing for both gameplay and menus. It handles BPM changes, time signatures, beat/step detection, and provides time conversion utilities.

Overview

The Conductor maintains the current song position and automatically dispatches signals when musical events occur (measures, beats, steps). It supports complex timing scenarios including:

Multiple BPM changes within a song
Arbitrary time signatures (4/4, 3/4, 7/8, etc.)
Audio/visual offsets and latency compensation
Precise time-to-beat/step conversions

Accessing the Conductor

// Get the singleton instance
var conductor = Conductor.instance;

// Access current timing information
trace(conductor.bpm);              // Current BPM
trace(conductor.currentBeat);      // Current beat (integer)
trace(conductor.currentBeatTime);  // Current beat (float with decimals)
trace(conductor.songPosition);     // Current position in milliseconds

Properties

Timing Properties

bpm

Float

Current beats per minute at the current song position. Automatically adjusts when time changes occur.

songPosition

Float

Current position in the song in milliseconds. Updated every frame via update().

currentBeat

Int

Current position in the song as an integer beat number.

currentBeatTime

Float

Current position in the song in beats, including fractional beats.

currentStep

Int

Current position in the song as an integer step number. There are 4 steps per beat.

currentStepTime

Float

Current position in the song in steps, including fractional steps.

currentMeasure

Int

Current position in the song as an integer measure number.

currentMeasureTime

Float

Current position in the song in measures, including fractional measures.

Duration Properties

beatLengthMs

Float

Duration of a beat in milliseconds, calculated from the current BPM and time signature.

stepLengthMs

Float

Duration of a step in milliseconds. Always 1/4 of beatLengthMs.

measureLengthMs

Float

Duration of a measure in milliseconds, calculated from beat length and time signature.

Time Signature Properties

timeSignatureNumerator

Int

The numerator of the current time signature (the 3 in 3/4).

timeSignatureDenominator

Int

The denominator of the current time signature (the 4 in 3/4).

beatsPerMeasure

Float

Number of beats in a measure. Equal to timeSignatureNumerator.

stepsPerMeasure

Int

Number of steps in a measure. Equal to timeSignatureNumerator * 4.

Offset Properties

instrumentalOffset

Float

Chart-specific offset in milliseconds to compensate for instrumental delays.

formatOffset

Float

Audio format offset (e.g., MP3 encoding delay).

globalOffset

Int

User-configured offset to compensate for input lag, loaded from save data.

audioVisualOffset

Int

User-configured offset to compensate for audio/visual lag, loaded from save data.

combinedOffset

Float

Sum of instrumentalOffset + formatOffset + globalOffset.

Methods

update()

Updates the conductor with the current song position and recalculates all timing properties.

public function update(?songPos:Float, applyOffsets:Bool = true, forceDispatch:Bool = false):Void

songPos

Float

The current position in the song in milliseconds. If omitted, uses FlxG.sound.music.time.

applyOffsets

Bool

default:"true"

Whether to apply combinedOffset to the song position.

forceDispatch

Bool

default:"false"

Force signal dispatch even if the current step/beat/measure hasn’t changed.

Example:

override function update(elapsed:Float):Void
{
  super.update(elapsed);
  
  // Update conductor every frame in gameplay
  Conductor.instance.update();
}

mapTimeChanges()

Applies song time changes (BPM/time signature changes) to the conductor.

public function mapTimeChanges(songTimeChanges:Array<SongTimeChange>):Void

songTimeChanges

Array<SongTimeChange>

required

Array of time change data from song metadata.

Example:

// Load time changes from song data
var song = SongRegistry.instance.fetchEntry("roses");
var chart = song.getDifficulty("hard");
Conductor.instance.mapTimeChanges(chart.getTimeChanges());

forceBPM()

Forces the conductor to use a specific BPM, ignoring time changes.

public function forceBPM(?bpm:Float):Void

bpm

Float

The BPM to force. Pass null to reset to time change-based BPM.

Avoid using this for setting BPM of menu music. Use metadata files instead. This is primarily for tools like the chart editor.

Example:

// Force to 150 BPM
Conductor.instance.forceBPM(150);

// Reset to normal time change behavior
Conductor.instance.forceBPM(null);

Time Conversion Methods

The Conductor provides several methods for converting between different time units.

getTimeInSteps()

Converts milliseconds to steps.

public function getTimeInSteps(ms:Float):Float

Float

required

Time in milliseconds.

Returns: Time in steps (float).

getStepTimeInMs()

Converts steps to milliseconds.

public function getStepTimeInMs(stepTime:Float):Float

stepTime

Float

required

Time in steps.

Returns: Time in milliseconds.

getBeatTimeInMs()

Converts beats to milliseconds.

public function getBeatTimeInMs(beatTime:Float):Float

beatTime

Float

required

Time in beats.

Returns: Time in milliseconds.

getTimeInMeasures()

Converts milliseconds to measures.

public function getTimeInMeasures(ms:Float):Float

Float

required

Time in milliseconds.

Returns: Time in measures (float).

getMeasureTimeInMs()

Converts measures to milliseconds.

public function getMeasureTimeInMs(measureTime:Float):Float

measureTime

Float

required

Time in measures.

Returns: Time in milliseconds. Example:

// Jump to beat 16
var targetMs = Conductor.instance.getBeatTimeInMs(16);
FlxG.sound.music.time = targetMs;

// Get current position in steps
var currentStep = Conductor.instance.getTimeInSteps(FlxG.sound.music.time);

getTimeWithDelta()

Returns a more accurate music time for higher framerates by including interpolated delta time.

public function getTimeWithDelta():Float

Returns: Song position with delta applied for smoother timing.

Signals

The Conductor dispatches signals when timing events occur. Use these to sync animations and gameplay to the music.

stepHit

FlxSignal

Fired when the conductor advances to a new step (16th note in 4/4 time).

beatHit

FlxSignal

Fired when the conductor advances to a new beat (quarter note in 4/4 time).

measureHit

FlxSignal

Fired when the conductor advances to a new measure.

Example:

override function create():Void
{
  super.create();
  
  // Listen for beat hits
  Conductor.beatHit.add(onBeatHit);
}

function onBeatHit():Void
{
  // Bump characters on every beat
  boyfriend.dance();
  dad.dance();
  
  // Camera zoom every 4 beats
  if (Conductor.instance.currentBeat % 4 == 0)
  {
    FlxG.camera.zoom += 0.015;
  }
}

override function destroy():Void
{
  Conductor.beatHit.remove(onBeatHit);
  super.destroy();
}

Static Methods

reset()

Resets the conductor by creating a new instance.

public static function reset():Void

Example:

// Reset conductor state when changing songs
Conductor.reset();

watchQuick()

Adds conductor properties to the Flixel debugger watch window.

public static function watchQuick(?target:Conductor):Void

target

Conductor

The conductor instance to watch. Defaults to Conductor.instance.

Example:

#if debug
Conductor.watchQuick();
#end

Understanding Steps, Beats, and Measures

The Conductor uses musical notation concepts:

Step: A subdivision of a beat. In 4/4 time with 4 steps per beat, a step equals a 16th note.
Beat: The basic unit of time in music. In 4/4 time, a beat equals a quarter note.
Measure: A grouping of beats. In 4/4 time, a measure contains 4 beats.

Time Signature Effects

4/4 time: 4 beats per measure, 16 steps per measure
- 120 BPM = 2 beats/second, 8 steps/second
3/4 time: 3 beats per measure, 12 steps per measure
- 120 BPM = 2 beats/second, 8 steps/second
7/8 time: 7 beats per measure (eighth notes!), 28 steps per measure
- 120 BPM = 4 beats/second, 16 steps/second

Example: Syncing to Music

class MyMusicState extends MusicBeatState
{
  var particles:FlxEmitter;
  
  override function create():Void
  {
    super.create();
    
    // Load song and set up conductor
    FlxG.sound.playMusic("assets/music/freakyMenu.ogg");
    Conductor.instance.forceBPM(102);
    
    // Create particle emitter
    particles = new FlxEmitter();
    add(particles);
    
    // Listen for beat hits
    Conductor.beatHit.add(onBeatHit);
  }
  
  override function update(elapsed:Float):Void
  {
    super.update(elapsed);
    
    // Update conductor every frame
    Conductor.instance.update();
  }
  
  function onBeatHit():Void
  {
    // Emit particles on every beat
    particles.start();
    
    // Do something special every 4 beats (every measure in 4/4 time)
    if (Conductor.instance.currentBeat % 4 == 0)
    {
      trace("Measure " + Conductor.instance.currentMeasure);
    }
  }
  
  override function destroy():Void
  {
    Conductor.beatHit.remove(onBeatHit);
    super.destroy();
  }
}

Core

Audio

Play

Data

Modding

Overview

Accessing the Conductor

Properties

Timing Properties

Duration Properties

Time Signature Properties

Offset Properties

Methods

update()

mapTimeChanges()

forceBPM()

Time Conversion Methods

getTimeInSteps()

getStepTimeInMs()

getBeatTimeInMs()

getTimeInMeasures()

getMeasureTimeInMs()

getTimeWithDelta()

Signals

Static Methods

reset()

watchQuick()

Understanding Steps, Beats, and Measures

Time Signature Effects

Example: Syncing to Music

See Also

Build docs developers (and LLMs) love

Core

Audio

Play

Data

Modding

​Overview

​Accessing the Conductor

​Properties

​Timing Properties

​Duration Properties

​Time Signature Properties

​Offset Properties

​Methods

​update()

​mapTimeChanges()

​forceBPM()

​Time Conversion Methods

​getTimeInSteps()

​getStepTimeInMs()

​getBeatTimeInMs()

​getTimeInMeasures()

​getMeasureTimeInMs()

​getTimeWithDelta()

​Signals

​Static Methods

​reset()

​watchQuick()

​Understanding Steps, Beats, and Measures

​Time Signature Effects

​Example: Syncing to Music

​See Also

Build docs developers (and LLMs) love

Overview

Accessing the Conductor

Properties

Timing Properties

Duration Properties

Time Signature Properties

Offset Properties

Methods

update()

mapTimeChanges()

forceBPM()

Time Conversion Methods

getTimeInSteps()

getStepTimeInMs()

getBeatTimeInMs()

getTimeInMeasures()

getMeasureTimeInMs()

getTimeWithDelta()

Signals

Static Methods

reset()

watchQuick()

Understanding Steps, Beats, and Measures

Time Signature Effects

Example: Syncing to Music

See Also