pub struct Sound { /* private fields */ }
Expand description
Sound data that can be played back.
All of the playback methods on this type return a SoundInstance
that
can be used to control the sound after it has started. If you just want
to ‘fire and forget’ a sound, you can discard it - the sound will
continue playing regardless.
Supported File Formats
Audio can be decoded from various common file formats via the new
and from_encoded
constructors. Individual
decoders can be enabled or disabled via Cargo feature flags.
Format | Cargo feature | Enabled by default? |
---|---|---|
WAV | audio_wav | Yes |
OGG Vorbis | audio_vorbis | Yes |
MP3 | audio_mp3 | Yes |
FLAC | audio_flac | No |
Performance
When you create an instance of Sound
, the audio data is loaded into memory. It is not
decoded until playback begins.
You can clone a sound cheaply, as it is reference-counted
internally. The underlying data will be shared by all of the clones (and, by extension,
all of the SoundInstance
s created from them).
Examples
The audio
example demonstrates how to play several different kinds of sound.
Implementations§
source§impl Sound
impl Sound
sourcepub fn new<P>(path: P) -> Result<Sound>where
P: AsRef<Path>,
pub fn new<P>(path: P) -> Result<Sound>where P: AsRef<Path>,
Creates a new sound from the given file.
Note that the data is not decoded until playback begins, so this function will not validate that the data being read is formatted correctly.
Errors
TetraError::FailedToLoadAsset
will be returned if the file could not be loaded.
sourcepub fn from_encoded(data: &[u8]) -> Sound
pub fn from_encoded(data: &[u8]) -> Sound
Creates a new sound from a slice of binary data, encoded in one of Tetra’s supported file formats.
This is useful in combination with include_bytes
, as it
allows you to include your audio data directly in the binary.
Note that the data is not decoded until playback begins, so this function will not validate that the data being read is formatted correctly.
sourcepub fn play(&self, ctx: &Context) -> Result<SoundInstance>
pub fn play(&self, ctx: &Context) -> Result<SoundInstance>
Plays the sound.
Errors
TetraError::NoAudioDevice
will be returned if no audio device is active.TetraError::InvalidSound
will be returned if the sound data could not be decoded.
sourcepub fn repeat(&self, ctx: &Context) -> Result<SoundInstance>
pub fn repeat(&self, ctx: &Context) -> Result<SoundInstance>
Plays the sound repeatedly.
Errors
TetraError::NoAudioDevice
will be returned if no audio device is active.TetraError::InvalidSound
will be returned if the sound data could not be decoded.
sourcepub fn spawn(&self, ctx: &Context) -> Result<SoundInstance>
pub fn spawn(&self, ctx: &Context) -> Result<SoundInstance>
Spawns a new instance of the sound that is not playing yet.
Errors
TetraError::NoAudioDevice
will be returned if no audio device is active.TetraError::InvalidSound
will be returned if the sound data could not be decoded.
sourcepub fn play_with(
&self,
ctx: &Context,
volume: f32,
speed: f32
) -> Result<SoundInstance>
pub fn play_with( &self, ctx: &Context, volume: f32, speed: f32 ) -> Result<SoundInstance>
Plays the sound, with the provided settings.
Errors
TetraError::NoAudioDevice
will be returned if no audio device is active.TetraError::InvalidSound
will be returned if the sound data could not be decoded.
sourcepub fn repeat_with(
&self,
ctx: &Context,
volume: f32,
speed: f32
) -> Result<SoundInstance>
pub fn repeat_with( &self, ctx: &Context, volume: f32, speed: f32 ) -> Result<SoundInstance>
Plays the sound repeatedly, with the provided settings.
Errors
TetraError::NoAudioDevice
will be returned if no audio device is active.TetraError::InvalidSound
will be returned if the sound data could not be decoded.
sourcepub fn spawn_with(
&self,
ctx: &Context,
volume: f32,
speed: f32
) -> Result<SoundInstance>
pub fn spawn_with( &self, ctx: &Context, volume: f32, speed: f32 ) -> Result<SoundInstance>
Spawns a new instance of the sound that is not playing yet, with the provided settings.
Errors
TetraError::NoAudioDevice
will be returned if no audio device is active.TetraError::InvalidSound
will be returned if the sound data could not be decoded.