Struct agb::sound::mixer::SoundChannel

pub struct SoundChannel { /* private fields */ }

Describes one sound which should be playing. This could be a sound effect or the background music. Use the factory methods on this to modify how it is played.

You must set stereo sounds with .stereo() or it will play as mono and at half the intended speed.

SoundChannels are very cheap to create, so don’t worry about creating a brand new one for every single sound you want to play.

SoundChannels can be either ‘low priority’ or ‘high priority’. A high priority sound channel will override ‘low priority’ sound channels which are already playing to ensure that it is always running. A ‘low priority’ sound channel will not override any other channel.

This is because you can only play up to 8 channels at once, and so high priority channels are prioritised over low priority channels to ensure that sounds that you always want playing will always play.

Example

Playing background music (stereo)

Background music is generally considered ‘high priority’ because you likely want it to play regardless of whether you have lots of sound effects playing. You create a high priority sound channel using new_high_priority.

// in global scope:
const MY_BGM: &[u8] = include_wav!("examples/sfx/my_bgm.wav");

// somewhere in code
let mut bgm = SoundChannel::new_high_priority(MY_BGM);
bgm.stereo().should_loop();
let _ = mixer.play_sound(bgm);

Playing a sound effect

// in global scope:
const JUMP_SOUND: &[u8] = include_wav!("examples/sfx/jump.wav");

// somewhere in code
let jump_sound = SoundChannel::new(JUMP_SOUND);
let _ = mixer.play_sound(jump_sound);

Implementations

impl SoundChannel

pub fn new(data: &'static [u8]) -> Self

Creates a new low priority SoundChannel.

A low priority sound channel will be overridden by a high priority one if the mixer runs out of channels.

Low priority sound channels are intended for sound effects.

Example

// in global scope:
const JUMP_SOUND: &[u8] = include_wav!("examples/sfx/jump.wav");

// somewhere in code
let jump_sound = SoundChannel::new(JUMP_SOUND);
let _ = mixer.play_sound(jump_sound);

pub fn new_high_priority(data: &'static [u8]) -> Self

Creates a new high priority SoundChannel.

A high priority sound channel will override low priority ones if the mixer runs out of channels. They will also never be overridden by other high priority channels.

High priority channels are intended for background music and for important, game breaking sound effects if you have any.

Example

// in global scope:
const MY_BGM: &[u8] = include_wav!("examples/sfx/my_bgm.wav");

// somewhere in code
let mut bgm = SoundChannel::new_high_priority(MY_BGM);
bgm.stereo().should_loop();
let _ = mixer.play_sound(bgm);

pub fn should_loop(&mut self) -> &mut Self

Sets that a sound channel should loop back to the start once it has finished playing rather than stopping.

pub fn restart_point( &mut self, restart_point: impl Into<Num<u32, 8>> ) -> &mut Self

Sets the point at which the sample should restart once it loops. Does nothing unless you also call should_loop().

Useful if your song has an introduction or similar.

pub fn playback(&mut self, playback_speed: impl Into<Num<u32, 8>>) -> &mut Self

Sets the speed at which this should channel should be played. Defaults to 1 with values between 0 and 1 being slower above 1 being faster.

Note that this only works for mono sounds. Stereo sounds will not change how fast they play.

pub fn panning(&mut self, panning: impl Into<Num<i16, 8>>) -> &mut Self

Sets how far left or right the sound effect should be played. Must be a value between -1 and 1 (inclusive). -1 means fully played on the left, 1 fully on the right and values in between allowing for partial levels.

Defaults to 0 (meaning equal on left and right) and doesn’t affect stereo sounds.

pub fn volume(&mut self, volume: impl Into<Num<i16, 8>>) -> &mut Self

Sets the volume for how loud the sound should be played. Note that if you play it too loud, the sound will clip sounding pretty terrible.

Must be a value >= 0 and defaults to 1.

pub fn stereo(&mut self) -> &mut Self

Sets that the sound effect should be played in stereo. Not setting this will result in the sound playing at half speed and mono. Setting this on a mono sound will cause some interesting results (and play it at double speed).

pub fn stop(&mut self)

Stops the sound from playing.

pub fn pos(&self) -> Num<u32, 8>

Gets how far along the sound has played.

pub fn set_pos(&mut self, pos: impl Into<Num<u32, 8>>) -> &mut Self

Sets the playback position