Module: Sunniesnow::Charter::BeatSeries

Included in:
Sunniesnow::Charter, TimeDependent
Defined in:
lib/sscharter/charter/beat.rb

Overview

Including this module adds the ability to keep track of the current beat and set BPM changes at the current beat. It provides methods #beat and #beat! to navigate through the beats.

The examples shown in the documentation below assume that self is a Sunniesnow::Charter instance.

Instance Attribute Summary collapse

DSL Methods collapse

Instance Method Summary collapse

Instance Attribute Details

#bpm_changes ⇒ BpmChangeList? (readonly)

It is nil if the offset has not been set by Sunniesnow::Charter#offset yet.

Returns:



177
178
179
 
# File 'lib/sscharter/charter/beat.rb', line 177

def bpm_changes
  @bpm_changes
end

#current_beat ⇒ Rational?

It is nil if the offset has not been set by Sunniesnow::Charter#offset yet.

Returns:

  • (Rational?) 


173
174
175
 
# File 'lib/sscharter/charter/beat.rb', line 173

def current_beat
  @current_beat
end

Instance Method Details

#beat(delta_beat = 0) ⇒ Rational Also known as: b

Increments the current beat by the given delta set by delta_beat. It is recommended that delta_beat be a Rational or an Integer for accuracy. Float will be converted to Rational, and a warning will be issued when a Float is used.

This method is also useful for inspecting the current beat. If the method is called without an argument, it simply returns the current beat. For this purpose, this method is equivalent to #beat!.

This method must be called after Sunniesnow::Charter#offset.

Examples:

Increment the current beat and inspect it

offset 0.1; bpm 120
p b       # Outputs 0, this is the initial value
p b 1     # Outputs 1, because it is incremented by 1 when it was 0
p b 1/2r  # Outputs 3/2, because it is incremented by 3/2 when it was 1
p time_at # Outputs 0.85, which is offset + 60s / BPM * beat

Time the notes

offset 0.1; bpm 120
t 0, 0; b 1
t 50, 0; b 1
# Now there are two tap notes, one at beat 0, and the other at beat 1

Parameters:

  • delta_beat (Rational, Integer) (defaults to: 0) —

    the delta to increment the current beat by.

Returns:

  • (Rational) —

    the new current beat.

Raises:

See Also:



220
221
222
223
224
225
226
227
228
229
230
231
 
# File 'lib/sscharter/charter/beat.rb', line 220

def beat delta_beat = 0
	raise OffsetError.new __method__ unless @current_beat
	case delta_beat
	when Integer, Rational
		@current_beat += delta_beat.to_r
	when Float
		warn 'float beat is not recommended'
		@current_beat += delta_beat.to_r
	else
		raise ArgumentError, 'invalid delta_beat'
	end
end

#beat!(beat = @current_beat) ⇒ Rational Also known as: b!

Sets the current beat to the given value. It is recommended that beat be a Rational or an Integer for accuracy. Float will be converted to Rational, and a warning will be issued.

When called without an argument, this method does nothing and returns the current beat. For this purpose, this method is equivalent to #beat.

This method must be called after Sunniesnow::Charter#offset.

Examples:

Set the current beat and inspect it

offset 0.1; bpm 120
p b!      # Outputs 0, this is the initial value
p b! 1    # Outputs 1, because it is set to 1
p b! 1/2r # Outputs 1/2, because it is set to 1/2
p time_at # Outputs 0.35, which is offset + 60s / BPM * beat

Parameters:

  • beat (Rational, Integer) (defaults to: @current_beat) —

    the new current beat.

Returns:

  • (Rational) —

    the new current beat.

Raises:

See Also:



252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/sscharter/charter/beat.rb', line 252

def beat! beat = @current_beat
	raise OffsetError.new __method__ unless @current_beat
	case beat
	when Integer, Rational
		@current_beat = beat.to_r
	when Float
		warn 'float beat is not recommended'
		@current_beat = beat.to_r
	else
		raise ArgumentError, 'invalid beat'
	end
end

#bpm(bpm) ⇒ BpmChangeList

Set the BPM starting at the current beat. This method must be called after Sunniesnow::Charter#offset. The method can be called multiple times, which is useful when the music changes its tempo from time to time.

Internally, this simply calls Sunniesnow::Charter::BpmChangeList#add on the BPM changes created by Sunniesnow::Charter#offset.

Parameters:

  • bpm (Numeric) —

    the BPM.

Returns:

Raises:



190
191
192
193
 
# File 'lib/sscharter/charter/beat.rb', line 190

def bpm bpm
	raise OffsetError.new __method__ unless @bpm_changes
	@bpm_changes.add @current_beat, bpm
end

#current_beat_state ⇒ BeatState

Note:

Internal API.

Returns:



278
279
280
 
# File 'lib/sscharter/charter/beat.rb', line 278

def current_beat_state
	BeatState.new @current_beat, @bpm_changes
end

#restore_beat_state(backup) ⇒ void

Note:

Internal API.

This method returns an undefined value.

Parameters:



285
286
287
288
289
 
# File 'lib/sscharter/charter/beat.rb', line 285

def restore_beat_state backup
	@current_beat = backup.current_beat
	@bpm_changes = backup.bpm_changes
	nil
end

#time_at(beat = @current_beat) ⇒ Float

Parameters:

  • beat (Rational) (defaults to: @current_beat)

Returns:

  • (Float)

Raises:



271
272
273
274
 
# File 'lib/sscharter/charter/beat.rb', line 271

def time_at beat = @current_beat
	raise OffsetError.new __method__ unless @bpm_changes
	@bpm_changes.time_at beat
end