Lovebpm

A LÖVE library for syncing events to the BPM of an audio track.

Installation

The lovebpm.lua file should be dropped into an existing project and required by it:

lovebpm = require "lovebpm"

Lovebpm requires LÖVE version 0.10.0 or above.

Getting Started

First a Track object should be created using the lovebpm.newTrack() function:

music = lovebpm.newTrack()

The update() method of each track should be called from within the love.update() function:

function love.update(dt)
  music:update()
end

The track's load() method should be called to load in the music. The load method takes a single argument: the music's filename or a SoundData object. The setBPM() method should be called with the BPM of the loaded track.

music:load("loop.ogg")
music:setBPM(127)

An event handler function for the beat event can be set. This will be called at the start of each beat when the song is playing, the beat number is passed to the handler function.

music:on("beat", function(n) print("beat:", n) end)

The music can be played by using the play() method.

music:play()

See the demo directory for a small example project.

Functions

lovebpm.newTrack()

Creates and returns a new Track object.

lovebpm.detectBPM(filename [, opts])

Tries to detect the BPM of a looped song. filename can be a filename or SoundData object. An opts table can be provided with additional options, consisting of the following:

Name	Default	Description
minbpm	75	Minimum allowed BPM
maxbpm	300	Maximum allowed BPM

Track:load(filename)

Loads an audio file or SoundData object.

Track:setBPM(n)

Sets the BPM of the current track; this is used when calculating the current beat.

Track:setVolume([volume])

Sets the volume of the track, by default this is 1.

Track:setPitch([pitch])

Sets the pitch of the track, by default this is 1.

Track:setLooping([loop])

Sets whether the track should loop when it reaches the end. By default this is false.

Track:setOffset([n])

Offsets the track's timing by n seconds. This function can be used to compensate for audio latency. By default this is 0.

Track:on(name, fn)

Sets an event handler for the event of the given name. The on() function can be called several times for the same event to set multiple handlers. The events which can be emitted by a track are as follows:

Name	Description	Arguments
beat	The start of a beat has occurred	current_beat
update	The track's update() function was called	track_delta_time
loop	The track has reached the end and looped
end	The track has reached the end and stopped

Track:play([restart])

Plays the track if it is stopped or paused. If restart is true then the track starts playing from the beginning.

Track:pause()

Pauses the track's progress, but retains the current play-position of the track.

Track:stop()

Stops the track, reseting the current play-position to the beginning.

Track:setTime(n)

Sets the current play-position of the track to n seconds.

Track:setBeat(n)

Sets the current play-position of the track to the given beat number.

Track:getTotalTime()

Returns the length of the track in seconds.

Track:getTotalBeats()

Returns the total number of beats in the track.

Track:getTime()

Returns the current play-position of the track.

Track:getBeat([multiplier])

Returns the current beat and subbeat of the track. For example, if the track is exactly half way between beats 3 and 4, the values 3 and 0.5 will be returned:

local beat, subbeat = music:getBeat()

Track:update()

Updates the track's internal state, and emits events if required. This should be called from the love.update() function.

License

This library is free software; you can redistribute it and/or modify it under the terms of the MIT license. See LICENSE for details.