Class: SFML::Music

Inherits:
Object
  • Object
show all
Defined in:
lib/sfml/audio/music.rb

Overview

A streamed audio source. Use this for long tracks (background music) so the file isn’t loaded into memory all at once.

bgm = SFML::Music.load("assets/track.ogg", looping: true, volume: 60)
bgm.play

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.from_memory(bytes, **opts) ⇒ Object

Stream music from a Ruby String of bytes (an in-memory MP3, OGG, FLAC, …). Useful for embedded audio or downloaded tracks that bypass the disk. The bytes must outlive the Music object — SFML keeps a pointer into them.

Raises:

  • (ArgumentError) 


19
20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/sfml/audio/music.rb', line 19

def self.from_memory(bytes, **opts)
  raise ArgumentError, "expected a String, got #{bytes.class}" unless bytes.is_a?(String)

  buf = FFI::MemoryPointer.new(:uint8, bytes.bytesize)
  buf.write_bytes(bytes)
  ptr = C::Audio.sfMusic_createFromMemory(buf, bytes.bytesize)
  raise Error, "sfMusic_createFromMemory returned NULL — unsupported format?" if ptr.null?

  m = _wrap(ptr, opts)
  m.instance_variable_set(:@_memory_pin, buf)   # keep buffer alive
  m
end

.load(path, **opts) ⇒ Object

Raises:



8
9
10
11
12
13
 
# File 'lib/sfml/audio/music.rb', line 8

def self.load(path, **opts)
  ptr = C::Audio.sfMusic_createFromFile(path.to_s)
  raise Error, "Could not load music from #{path.inspect}" if ptr.null?

  _wrap(ptr, opts)
end

Instance Method Details

#attenuation ⇒ Object 



152
 
# File 'lib/sfml/audio/music.rb', line 152

def attenuation = C::Audio.sfMusic_getAttenuation(@handle)

#attenuation=(value) ⇒ Object 



154
155
156
 
# File 'lib/sfml/audio/music.rb', line 154

def attenuation=(value)
  C::Audio.sfMusic_setAttenuation(@handle, value.to_f)
end

#channel_count ⇒ Object

—- Stream introspection —-



172
 
# File 'lib/sfml/audio/music.rb', line 172

def channel_count = C::Audio.sfMusic_getChannelCount(@handle)

#cone ⇒ Object 



99
100
101
 
# File 'lib/sfml/audio/music.rb', line 99

def cone
  SoundCone.from_native(C::Audio.sfMusic_getCone(@handle))
end

#cone=(value) ⇒ Object 



103
104
105
106
107
108
109
110
111
112
 
# File 'lib/sfml/audio/music.rb', line 103

def cone=(value)
  cone =
    case value
    when SoundCone then value
    when Hash      then SoundCone.new(**value)
    else
      raise ArgumentError, "Music#cone= expects SoundCone or Hash; got #{value.class}"
    end
  C::Audio.sfMusic_setCone(@handle, cone.to_native)
end

#direction ⇒ Object 



87
88
89
90
 
# File 'lib/sfml/audio/music.rb', line 87

def direction
  v = C::Audio.sfMusic_getDirection(@handle)
  Vector3.new(v[:x], v[:y], v[:z])
end

#direction=(value) ⇒ Object 



92
93
94
95
96
97
 
# File 'lib/sfml/audio/music.rb', line 92

def direction=(value)
  vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
  packed = C::System::Vector3f.new
  packed[:x] = vec.x.to_f; packed[:y] = vec.y.to_f; packed[:z] = vec.z.to_f
  C::Audio.sfMusic_setDirection(@handle, packed)
end

#directional_attenuation_factor ⇒ Object 



225
226
227
 
# File 'lib/sfml/audio/music.rb', line 225

def directional_attenuation_factor
  C::Audio.sfMusic_getDirectionalAttenuationFactor(@handle)
end

#directional_attenuation_factor=(v) ⇒ Object 



229
230
231
 
# File 'lib/sfml/audio/music.rb', line 229

def directional_attenuation_factor=(v)
  C::Audio.sfMusic_setDirectionalAttenuationFactor(@handle, v.to_f)
end

#doppler_factor ⇒ Object 



84
 
# File 'lib/sfml/audio/music.rb', line 84

def doppler_factor    = C::Audio.sfMusic_getDopplerFactor(@handle)

#doppler_factor=(v) ⇒ Object 



85
 
# File 'lib/sfml/audio/music.rb', line 85

def doppler_factor=(v) C::Audio.sfMusic_setDopplerFactor(@handle, v.to_f); end

#duration ⇒ Object 



54
 
# File 'lib/sfml/audio/music.rb', line 54

def duration = Time.from_native(C::Audio.sfMusic_getDuration(@handle))

#effect_processor=(callable) ⇒ Object

See Sound#effect_processor= — same audio-thread DSP callback.



115
116
117
118
 
# File 'lib/sfml/audio/music.rb', line 115

def effect_processor=(callable)
  @effect_cb = callable.nil? ? nil : Audio._build_effect_processor(callable)
  C::Audio.sfMusic_setEffectProcessor(@handle, @effect_cb, nil)
end

#loop_points ⇒ Object

The portion of the track that loops when ‘looping = true`. Returns `[offset, length]` of `SFML::Time`s; defaults to the whole track. Set with `loop_points = [Time, Time]`.



178
179
180
181
 
# File 'lib/sfml/audio/music.rb', line 178

def loop_points
  span = C::Audio.sfMusic_getLoopPoints(@handle)
  [Time.from_native(span[:offset]), Time.from_native(span[:length])]
end

#loop_points=(value) ⇒ Object

Raises:

  • (ArgumentError) 


183
184
185
186
187
188
189
190
191
 
# File 'lib/sfml/audio/music.rb', line 183

def loop_points=(value)
  offset_t, length_t = value
  raise ArgumentError, "expected [offset_time, length_time]" unless offset_t && length_t

  span = C::Audio::TimeSpan.new
  span[:offset][:microseconds] = offset_t.is_a?(Time) ? offset_t.microseconds : Time.seconds(offset_t.to_f).microseconds
  span[:length][:microseconds] = length_t.is_a?(Time) ? length_t.microseconds : Time.seconds(length_t.to_f).microseconds
  C::Audio.sfMusic_setLoopPoints(@handle, span)
end

#looping=(value) ⇒ Object 



125
126
127
128
 
# File 'lib/sfml/audio/music.rb', line 125

def looping=(value)
  @looping = value ? true : false
  C::Audio.sfMusic_setLooping(@handle, @looping)
end

#looping? ⇒ Boolean

Cached on the Ruby side; see Sound#looping? for the why.

Returns:

  • (Boolean) 


121
122
123
 
# File 'lib/sfml/audio/music.rb', line 121

def looping?
  @looping
end

#max_distance ⇒ Object 



213
 
# File 'lib/sfml/audio/music.rb', line 213

def max_distance = C::Audio.sfMusic_getMaxDistance(@handle)

#max_distance=(v) ⇒ Object 



215
216
217
 
# File 'lib/sfml/audio/music.rb', line 215

def max_distance=(v)
  C::Audio.sfMusic_setMaxDistance(@handle, v.to_f)
end

#max_gain ⇒ Object 



207
 
# File 'lib/sfml/audio/music.rb', line 207

def max_gain = C::Audio.sfMusic_getMaxGain(@handle)

#max_gain=(v) ⇒ Object 



209
210
211
 
# File 'lib/sfml/audio/music.rb', line 209

def max_gain=(v)
  C::Audio.sfMusic_setMaxGain(@handle, v.to_f)
end

#min_distance ⇒ Object 



158
 
# File 'lib/sfml/audio/music.rb', line 158

def min_distance = C::Audio.sfMusic_getMinDistance(@handle)

#min_distance=(value) ⇒ Object 



160
161
162
 
# File 'lib/sfml/audio/music.rb', line 160

def min_distance=(value)
  C::Audio.sfMusic_setMinDistance(@handle, value.to_f)
end

#min_gain ⇒ Object 



201
 
# File 'lib/sfml/audio/music.rb', line 201

def min_gain = C::Audio.sfMusic_getMinGain(@handle)

#min_gain=(v) ⇒ Object 



203
204
205
 
# File 'lib/sfml/audio/music.rb', line 203

def min_gain=(v)
  C::Audio.sfMusic_setMinGain(@handle, v.to_f)
end

#pan ⇒ Object

—- 3D-audio extras (mirror of Sound’s) —-



195
 
# File 'lib/sfml/audio/music.rb', line 195

def pan = C::Audio.sfMusic_getPan(@handle)

#pan=(v) ⇒ Object 



197
198
199
 
# File 'lib/sfml/audio/music.rb', line 197

def pan=(v)
  C::Audio.sfMusic_setPan(@handle, v.to_f)
end

#pause ⇒ Object 



46
 
# File 'lib/sfml/audio/music.rb', line 46

def pause  = C::Audio.sfMusic_pause(@handle)

#paused? ⇒ Boolean

Returns:

  • (Boolean) 


51
 
# File 'lib/sfml/audio/music.rb', line 51

def paused?  = status == :paused

#pitch ⇒ Object 



136
 
# File 'lib/sfml/audio/music.rb', line 136

def pitch = C::Audio.sfMusic_getPitch(@handle)

#pitch=(value) ⇒ Object 



138
139
140
 
# File 'lib/sfml/audio/music.rb', line 138

def pitch=(value)
  C::Audio.sfMusic_setPitch(@handle, value.to_f)
end

#play ⇒ Object 



45
 
# File 'lib/sfml/audio/music.rb', line 45

def play   = C::Audio.sfMusic_play(@handle)

#playing? ⇒ Boolean

Returns:

  • (Boolean) 


50
 
# File 'lib/sfml/audio/music.rb', line 50

def playing? = status == :playing

#playing_offset ⇒ Object

Current playback head as a SFML::Time. Reads from the underlying OpenAL source — only meaningful while the music is playing or paused (not after #stop).



59
60
61
 
# File 'lib/sfml/audio/music.rb', line 59

def playing_offset
  Time.from_native(C::Audio.sfMusic_getPlayingOffset(@handle))
end

#playing_offset=(value) ⇒ Object

Seek to ‘value` (a SFML::Time, or seconds as a Numeric). Works while the music is playing, paused, or stopped.



65
66
67
68
 
# File 'lib/sfml/audio/music.rb', line 65

def playing_offset=(value)
  t = value.is_a?(Time) ? value : Time.seconds(value.to_f)
  C::Audio.sfMusic_setPlayingOffset(@handle, t.to_native)
end

#position ⇒ Object

3D positional audio — see SFML::Sound for the why.



143
144
145
 
# File 'lib/sfml/audio/music.rb', line 143

def position
  Vector3.from_native(C::Audio.sfMusic_getPosition(@handle))
end

#position=(value) ⇒ Object 



147
148
149
150
 
# File 'lib/sfml/audio/music.rb', line 147

def position=(value)
  vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
  C::Audio.sfMusic_setPosition(@handle, vec.to_native_f)
end

#relative_to_listener=(value) ⇒ Object 



166
167
168
 
# File 'lib/sfml/audio/music.rb', line 166

def relative_to_listener=(value)
  C::Audio.sfMusic_setRelativeToListener(@handle, value ? true : false)
end

#relative_to_listener? ⇒ Boolean

Returns:

  • (Boolean) 


164
 
# File 'lib/sfml/audio/music.rb', line 164

def relative_to_listener? = C::Audio.sfMusic_isRelativeToListener(@handle)

#sample_rate ⇒ Object 



173
 
# File 'lib/sfml/audio/music.rb', line 173

def sample_rate   = C::Audio.sfMusic_getSampleRate(@handle)

#spatialization_enabled=(v) ⇒ Object 



221
222
223
 
# File 'lib/sfml/audio/music.rb', line 221

def spatialization_enabled=(v)
  C::Audio.sfMusic_setSpatializationEnabled(@handle, v ? true : false)
end

#spatialization_enabled? ⇒ Boolean

Returns:

  • (Boolean) 


219
 
# File 'lib/sfml/audio/music.rb', line 219

def spatialization_enabled? = C::Audio.sfMusic_isSpatializationEnabled(@handle)

#status ⇒ Object 



49
 
# File 'lib/sfml/audio/music.rb', line 49

def status   = C::Audio::STATUSES[C::Audio.sfMusic_getStatus(@handle)]

#stop ⇒ Object 



47
 
# File 'lib/sfml/audio/music.rb', line 47

def stop   = C::Audio.sfMusic_stop(@handle)

#stopped? ⇒ Boolean

Returns:

  • (Boolean) 


52
 
# File 'lib/sfml/audio/music.rb', line 52

def stopped? = status == :stopped

#velocity ⇒ Object

3D velocity, Doppler factor, direction, cone — see Sound for the same methods on the simpler buffered source.



72
73
74
75
 
# File 'lib/sfml/audio/music.rb', line 72

def velocity
  v = C::Audio.sfMusic_getVelocity(@handle)
  Vector3.new(v[:x], v[:y], v[:z])
end

#velocity=(value) ⇒ Object 



77
78
79
80
81
82
 
# File 'lib/sfml/audio/music.rb', line 77

def velocity=(value)
  vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
  packed = C::System::Vector3f.new
  packed[:x] = vec.x.to_f; packed[:y] = vec.y.to_f; packed[:z] = vec.z.to_f
  C::Audio.sfMusic_setVelocity(@handle, packed)
end

#volume ⇒ Object 



130
 
# File 'lib/sfml/audio/music.rb', line 130

def volume = C::Audio.sfMusic_getVolume(@handle)

#volume=(value) ⇒ Object 



132
133
134
 
# File 'lib/sfml/audio/music.rb', line 132

def volume=(value)
  C::Audio.sfMusic_setVolume(@handle, value.to_f)
end