Events Reference

Fired once after a GP file is fully parsed and loaded.

plugin.on("file.open", function(e)
  local s = e.song
  print(s.title .. " by " .. s.artist)
  print("Tempo: " .. s.tempo .. " BPM  |  " .. s.time_signature)
end)

Fired when the user closes the current file. No payload — e is an empty table.

No payload — the event table is empty.

plugin.on("file.close", function(_)
  -- Reset any UI state.
  plugin.set_label_text(my_label, "No file open")
end)

Fired when the user starts playback. Useful for arming UI state, switching from manual practice mode to song-synced behavior, or caching the current song metadata at the moment playback begins.

plugin.on("playback.start", function(e)
  local song = e.song
  plugin.set_label_text(status_label,
    "Playback started at " .. song.tempo .. " BPM")
end)

Fired when playback stops, either because the user stopped it or because the song finished naturally.

plugin.on("playback.stop", function(e)
  if e.completed then
    plugin.set_label_text(status_label, "Song finished")
  else
    plugin.set_label_text(status_label, "Playback stopped")
  end
end)

Fired after every view refresh (scroll, resize, zoom, etc.). No payload. Use sparingly — this can fire frequently.

No payload — the event table is empty.

plugin.on("render", function(_)
  -- e.g. sync an overlay position after the tab redraws.
end)

Fired once per beat during playback, before note events for that beat. Useful for progress bars or beat counters.

plugin.on("beat", function(e)
  local pct = e.beat_number / e.total_beats * 100
  plugin.set_label_text(progress_label,
    string.format("Beat %d / %d  (%.0f%%)",
      e.beat_number, e.total_beats, pct))
end)

Fired once per GP beat slot during playback, carrying beat-level effect data. A GP beat slot is one rhythmic unit (eighth note, sixteenth, etc.) — not necessarily a musical beat. Use beat.metronome_pulse instead if you need to fire exactly once per musical beat.

plugin.on("beat.in_measure", function(e)
  if e.repeat_open then
    print("Repeat section starts at measure " .. e.measure)
  end
  if e.repeat_close > 0 then
    print("Repeat closes (x" .. e.repeat_close .. ")")
  end
end)

Fired exactly once per musical beat during playback — N times per measure where N is the time signature numerator. Unlike beat.in_measure (which fires once per GP beat slot), this event fires at the correct musical beat boundaries even when notes span multiple beats. The app splits long note sleeps internally to guarantee accurate timing.

plugin.on("beat.metronome_pulse", function(e)
  -- e.musical_beat == 1 is the downbeat (accent it)
  local is_downbeat = e.musical_beat == 1
  play_click(is_downbeat)
  plugin.set_label_text(status_label,
    "Beat " .. e.musical_beat .. " of " .. e.numerator .. "/" .. e.denominator)
end)

Fired for every individual note during playback. A single beat can produce multiple note events simultaneously (one per sounding string). Note events fire after the beat and beat.in_measure events for the same position.

plugin.on("note", function(e)
  -- Skip ties to avoid re-triggering already-ringing notes.
  if e.tie_destination then return end

  -- Build a human-readable description of the note.
  local parts = {
    string.format("Track %d | M%d B%d | Str %d Fret %d",
      e.track + 1, e.measure, e.beat, e.string, e.fret)
  }
  if e.hammer_on  then parts[#parts+1] = "H"  end
  if e.pull_off   then parts[#parts+1] = "P"  end
  if e.palm_mute  then parts[#parts+1] = "PM" end
  if e.let_ring   then parts[#parts+1] = "LR" end

  plugin.set_label_text(my_label, table.concat(parts, "  "))
end)