abstract class `SF::SoundStream`
inherits `SF::SoundSource` #

Abstract base class for streamed audio sources

Unlike audio buffers (see SF::SoundBuffer), audio streams are never completely loaded in memory. Instead, the audio data is acquired continuously while the stream is playing. This behavior allows to play a sound with no loading delay, and keeps the memory consumption very low.

Sound sources that need to be streamed are usually big files (compressed audio musics that would eat hundreds of MB in memory) or files that would take a lot of time to be received (sounds played over the network).

SF::SoundStream is a base class that doesn't care about the stream source, which is left to the derived class. SFML provides a built-in specialization for big files (see SF::Music). No network stream source is provided, but you can write your own by combining this class with the network module.

A derived class has to override two virtual functions:

on_get_data fills a new chunk of audio data to be played
on_seek changes the current playing position in the source

It is important to note that each SoundStream is played in its own separate thread, so that the streaming loop doesn't block the rest of the program. In particular, the OnGetData and OnSeek virtual functions may sometimes be called from this separate thread. It is important to keep this in mind, because you may have to take care of synchronization issues if you share data between threads.

Usage example:

class CustomStream < SF::SoundStream
  def initialize(location : String)
    # Open the source and get audio settings
    # [...]

    # Initialize the stream -- important!
    super(channel_count, sample_rate)
  end

  def on_get_data
    # Return a slice with audio data from the stream source
    # (note: must not be empty if you want to continue playing)
    Slice.new(samples.to_unsafe, samples.size)
  end

  def on_seek(time_offset)
    # Change the current position in the stream source
  end
end

# Usage
stream = CustomStream.new("path/to/stream")
stream.play

See also: SF::Music

Direct known subclasses

SF::Music

Constants#

`NoLoop = -1`#

"Invalid" end_seeks value, telling us to continue uninterrupted

Constructors#

`.new(channel_count : Int, sample_rate : Int)`#

Define the audio stream parameters

This function must be called by derived classes as soon as they know the audio settings of the stream to play. Any attempt to manipulate the stream (play(), ...) before calling this function will fail. It can be called multiple times if the settings of the audio stream change, but only when the stream is stopped.

channel_count - Number of channels of the stream
sample_rate - Sample rate, in samples per second

abstract class SF::SoundStream inherits SF::SoundSource #

Direct known subclasses

Constants#

NoLoop = -1#

Constructors#

.new(channel_count : Int, sample_rate : Int)#

Methods#

#channel_count : Int32#

#finalize#

#loop : Bool#

#loop=(loop : Bool)#

abstract #on_get_data : Slice(Int16) | ::Nil#

#on_loop : Int64#

abstract #on_seek(time_offset : Time)#

#pause#

#play#

#playing_offset : Time#

#playing_offset=(time_offset : Time)#

#processing_interval=(interval : Time)#

#sample_rate : Int32#

#status : SoundSource::Status#

#stop#

abstract class `SF::SoundStream`
inherits `SF::SoundSource` #

`NoLoop = -1`#

`.new(channel_count : Int, sample_rate : Int)`#

`#channel_count : Int32`#

`#finalize`#

`#loop : Bool`#

`#loop=(loop : Bool)`#

abstract `#on_get_data : Slice(Int16) | ::Nil`#

`#on_loop : Int64`#

abstract `#on_seek(time_offset : Time)`#

`#pause`#

`#play`#

`#playing_offset : Time`#

`#playing_offset=(time_offset : Time)`#

`#processing_interval=(interval : Time)`#

`#sample_rate : Int32`#

`#status : SoundSource::Status`#

`#stop`#