9.3. Hooking into Aqualung Events

Aqualung allows you to add hooks to certain events to have extension code executed when those events occur. Hooks are added by calling the `add_hook' function with a string and a function. The string is the type of hook you are adding, and the function is the function to call when the related event occurs. You can have multiple hook functions added to the same hook type, and they will be executed in order of addition.

Hook 1: track_change

The track_change hooks are called whenever a new track starts playing. They are not called until after the current file has been changed to the new file. Inside this hook, you can call the `m' and `i' playlist formatting functions to access the metadata of the newly loaded file.

add_hook("track_change", function ()
print("File: " .. current_file() .. " Artist: " .. m("artist"))
end)

Prints the filename and artist of the new file.

Hook 2: track_position_change

The track_position_change hooks are called whenever the scale/position of the current track changes. Generally, it is called a few times a second. This can be used to keep track of aqualung's current position in the file, and is passed a floating point argument of the percent complete. Note that tracks that do not have a set number of samples (such as internet radio streams) will not have this hook called when they are playing.

add_hook("track_position_change", function ()
print(current_file() .. " " .. string.format("%0.2f%%", current_file_percent_complete()))
end)

Prints the filename and percent complete of the currently playing file.