FMExStream Class
Unlike the FMExAudioPlayer and FMExAudio decoupling, the FMExStream class acts both as an audio storage container and a playback mechanism. FMExAudio decodes and uncompresses audio in full, where as FMExStream stores audio data in its native file format. This is preferable for long-playing compressed formats such Ogg Vorbis, or MP3, or sequenced formats like MOD or MIDI. A two minute 44.1 kHz, 16 bit, stereo sample would use approximately 20MB of RAM as an FMExAudio instance, but can be streamed from a high-quality Ogg or MP3 format using less than 500 KB of RAM with the FMExStream class.
Important: Use the FolderItem.OpenAsFMExStream class extension or the FMEx.CreateStream method to create a new FMExStream instance. This class cannot be constructed using the New keyword.
Important: You must successfully initialize FMOD Ex via the FMEx.StartUp method before creating FMExStream objects. Also note that all existing FMExStream instances become invalidated after calling FMEx.ShutDown. Please see the Restarting FMOD Ex section for details on how to properly restart FMOD Ex should the need arise.
Note: The FMExStream class is ideal for long-format compressed audio such music or narration, but requires more CPU resources to decode data on-the-fly and has some playback limitations. The FMExAudio class is better suited for short audio samples which may playback multiple times simultaneously (game sound effects for example).
Properties
-
ByteLength As Integer
Returns the total number of bytes in the decompressed/decoded audio data. -
Channels As Integer
Returns the number of channels in the audio data. E.g. a mono sound will return 1 channel, a stereo sound will return 2, etc. -
Depth As Integer
Returns the bit depth of the audio data. Depth is bits per sample, per channel. Typical values are 8, 16, 24, or 32. -
Duration As Integer
Returns the total duration of the audio in milliseconds when played back at its default frequency. -
Format As Integer
Returns the audio data's format, which describes the bit layout.
Possible return values: -
Frequency As Integer
Returns the audio's native sample frequency in Hz. E.g. CD audio runs in realtime at 44100 Hz. -
Handle As Integer
Mostly for internal use. Returns the FMOD_SOUND handle which can be used in custom declare statements. -
SampleLength As Integer
Methods
-
Clone As FMExStream
Returns a new stream that shares the audio data buffer with this stream. This can be used to stream the same audio multiple times simultaneously, or play different parts of the same stream simultaneously without duplicating the audio data.
Note: This will currently return Nil if called from the FMExStreamSentence subclass. -
Play
Plays the stream from the beginning. Audio playback will stop when the end of the stream is reached. -
PlayLooping ( count As Integer = -1 )
Plays the stream from the beginning. The optional count parameter defines how many times to loop after the first playback. A count of 0 will play once, 1 will play twice, etc. The default count of -1 will loop indefinitely. -
ReadData ( fillblock As MemoryBlock, numbytes As Integer = 0 ) As Integer
Used to read the decoded/decompressed PCM audio data starting from the seek position (see the SeekData method). The return value is the actual number of bytes read. This fills the passed MemoryBlock with the requested number of bytes. If the MemoryBlock is sized it will be filled in its entirety. If the optional numbytes parameter is non-zero but less than MemoryBlock.Size then the block will be filled up to numbytes. If the MemoryBlock is a Ptr (has no size) then numbytes must be greater than zero and the Ptr is filled to numbytes.
Important: Always call SeekData(0) to read from the start of the stream. FMOD Ex will normally pre-seek streams a bit to get them ready to play, and normal playback and plackback cursor manipulation may also seek the stream.
Note: If numbytes surpasses the end of the stream data the actual number of bytes returned will be truncated. When the number of returned bytes is less than the requested number of bytes you've reached the end of the data. -
Reinitialize As integer
Refreshes the internal FMOD Ex pointers using the stream's existing data storage. This is mostly only useful during restarts. -
SetLoopPoints ( loopstart As Integer, loopend As Integer, usems As Boolean = False )
Sets loop points which FMOD Ex will use when looping the audio rather simply looping the entire waveform. If the optional usems parameter is True, loopstart and loopend are positions in milliseconds, otherwise they are sample offsets. -
SeekData ( pcm As Integer )