Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rxi/lovebpm
A LÖVE library for syncing events to the BPM of an audio track
https://github.com/rxi/lovebpm
Last synced: 2 months ago
JSON representation
A LÖVE library for syncing events to the BPM of an audio track
- Host: GitHub
- URL: https://github.com/rxi/lovebpm
- Owner: rxi
- License: mit
- Created: 2016-07-02T13:34:41.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2021-08-06T03:57:23.000Z (over 3 years ago)
- Last Synced: 2024-11-02T10:34:02.507Z (2 months ago)
- Language: Lua
- Size: 255 KB
- Stars: 77
- Watchers: 5
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-love2d - lovebpm - A LÖVE library for syncing events to the BPM of an audio track. (Music)
README
# Lovebpm
A [LÖVE](https://love2d.org/) library for syncing events to the BPM of an audio
track.
## Installation
The [lovebpm.lua](lovebpm.lua?raw=1) file should be dropped into an existing
project and required by it:
```lua
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:
```lua
music = lovebpm.newTrack()
```
The `update()` method of each track should be called from within the
`love.update()` function:
```lua
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.
```lua
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.
```lua
music:on("beat", function(n) print("beat:", n) end)
```
The music can be played by using the `play()` method.
```lua
music:play()
```
See the [demo](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:
```lua
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](LICENSE) for details.