Difference between revisions of "Playing Sound and Music"
| (2 intermediate revisions by one other user not shown) | |||
| Line 18: | Line 18: | ||
== Playing a sound == | == Playing a sound == | ||
Here is a sample to play a sound inside your app. It uses the play method of the Sound class: | Here is a sample to play a sound inside your app. It uses the play method of the Sound class: | ||
| − | < | + | <syntaxhighlight lang="lua"> |
-- Load a new sound and assign it to a variable | -- Load a new sound and assign it to a variable | ||
local yourSound = Sound.new("yourSoundFile.mp3") | local yourSound = Sound.new("yourSoundFile.mp3") | ||
-- Now play the sound | -- Now play the sound | ||
yourSound:play() | yourSound:play() | ||
| − | </ | + | </syntaxhighlight> |
As you can see, it is very easy to play a sound effect or a music file. The play method of the Sound class has three optional parameters: | As you can see, it is very easy to play a sound effect or a music file. The play method of the Sound class has three optional parameters: | ||
| Line 31: | Line 31: | ||
With the '''startTime''', you can control the starting point in milliseconds, from where a sound is played back. The '''loop''' parameter will control if the sound will be played repeatedly for the given number of times. The '''paused''' parameter will tell Gideros if the sound should be paused upon creation (useful for SoundChannel). Here is a simple example that will play a sound starting from 200 milliseconds and repeat itself 5 times: | With the '''startTime''', you can control the starting point in milliseconds, from where a sound is played back. The '''loop''' parameter will control if the sound will be played repeatedly for the given number of times. The '''paused''' parameter will tell Gideros if the sound should be paused upon creation (useful for SoundChannel). Here is a simple example that will play a sound starting from 200 milliseconds and repeat itself 5 times: | ||
| − | < | + | <syntaxhighlight lang="lua"> |
yourSound:play(200, 5) | yourSound:play(200, 5) | ||
| − | </ | + | </syntaxhighlight> |
If you want to let a sound play repeatedly, then just set the loop value to math.huge: | If you want to let a sound play repeatedly, then just set the loop value to math.huge: | ||
| − | < | + | <syntaxhighlight lang="lua"> |
yourSound:play(0, math.huge) | yourSound:play(0, math.huge) | ||
| − | </ | + | </syntaxhighlight> |
== Using sound channels == | == Using sound channels == | ||
Playing back sounds inside your app is nice but sometimes you want to have a little bit more control over things. For this Gideros uses sound channels. How are they created or retrieved you might ask? Piece of cake! Whenever you play a sound, assign the returning value (the sound channel) to a variable. Like this: | Playing back sounds inside your app is nice but sometimes you want to have a little bit more control over things. For this Gideros uses sound channels. How are they created or retrieved you might ask? Piece of cake! Whenever you play a sound, assign the returning value (the sound channel) to a variable. Like this: | ||
| − | < | + | <syntaxhighlight lang="lua"> |
local yourChannel = yourSound:play() | local yourChannel = yourSound:play() | ||
| − | </ | + | </syntaxhighlight> |
There is one event that will tell you when a sound channel has finished playing a sound file: Event.COMPLETE. | There is one event that will tell you when a sound channel has finished playing a sound file: Event.COMPLETE. | ||
Next is a small example on how the Event.COMPLETE event can be used: | Next is a small example on how the Event.COMPLETE event can be used: | ||
| − | < | + | <syntaxhighlight lang="lua"> |
-- Load a music file | -- Load a music file | ||
local snd = Sound.new("DST-Psykick.mp3") | local snd = Sound.new("DST-Psykick.mp3") | ||
| Line 61: | Line 61: | ||
-- finishes playing | -- finishes playing | ||
chan:addEventListener(Event.COMPLETE,onSoundComplete) | chan:addEventListener(Event.COMPLETE,onSoundComplete) | ||
| − | </ | + | </syntaxhighlight> |
== Releasing a sound == | == Releasing a sound == | ||
You don’t have to release a sound manually. It will be collected once the app ends. But if you need to release a sound during the life of your app, then just set the corresponding channel to nil: | You don’t have to release a sound manually. It will be collected once the app ends. But if you need to release a sound during the life of your app, then just set the corresponding channel to nil: | ||
| − | < | + | <syntaxhighlight lang="lua"> |
yourSound = nil | yourSound = nil | ||
| − | </ | + | </syntaxhighlight> |
'''Note:''' If the sound is currently playing, the sound will be released after it finishes playing. | '''Note:''' If the sound is currently playing, the sound will be released after it finishes playing. | ||
| Line 73: | Line 73: | ||
== Stopping a sound == | == Stopping a sound == | ||
If you want to stop a playing sound, then use your sound channel and its stop method for it: | If you want to stop a playing sound, then use your sound channel and its stop method for it: | ||
| − | < | + | <syntaxhighlight lang="lua"> |
sndChannel:stop() | sndChannel:stop() | ||
| − | </ | + | </syntaxhighlight> |
== Getting length of a sound file == | == Getting length of a sound file == | ||
Sometimes you need to know how long a sound file is exactly. To determine the length of a sound file you can use the getLength method. Use it with your sound channel: | Sometimes you need to know how long a sound file is exactly. To determine the length of a sound file you can use the getLength method. Use it with your sound channel: | ||
| − | < | + | <syntaxhighlight lang="lua"> |
local sndLength = sndChannel:getLength() | local sndLength = sndChannel:getLength() | ||
| − | </ | + | </syntaxhighlight> |
After this line is executed, sndLength will hold the length of the sound in milliseconds. | After this line is executed, sndLength will hold the length of the sound in milliseconds. | ||
| Line 88: | Line 88: | ||
Before you break some ears with loud sounds, you better give your users the possibility to control the volume of the sounds your app is playing. For this, there are two methods, setVolume, and getVolume. | Before you break some ears with loud sounds, you better give your users the possibility to control the volume of the sounds your app is playing. For this, there are two methods, setVolume, and getVolume. | ||
To get the volume of a sound, try this: | To get the volume of a sound, try this: | ||
| − | < | + | <syntaxhighlight lang="lua"> |
local volume = sndChannel:getVolume() | local volume = sndChannel:getVolume() | ||
| − | </ | + | </syntaxhighlight> |
And to set the volume of a channel, use setVolume like this: | And to set the volume of a channel, use setVolume like this: | ||
| − | < | + | <syntaxhighlight lang="lua"> |
sndChannel:setVolume(0.5) | sndChannel:setVolume(0.5) | ||
| − | </ | + | </syntaxhighlight> |
The volume levels ranging from 0.0 to 1.0. The later means maximum volume. | The volume levels ranging from 0.0 to 1.0. The later means maximum volume. | ||
| Line 101: | Line 101: | ||
== Getting the current position of a sound playing == | == Getting the current position of a sound playing == | ||
When you need to pause a sound or display the current position of a sound playing, you need to determine the current position of a channel. For this use the getPosition method with your channel: | When you need to pause a sound or display the current position of a sound playing, you need to determine the current position of a channel. For this use the getPosition method with your channel: | ||
| − | < | + | <syntaxhighlight lang="lua"> |
local currSndPos = sndChannel:getPosition() | local currSndPos = sndChannel:getPosition() | ||
| − | </ | + | </syntaxhighlight> |
The position is determined in milliseconds. So if you need to pause a sound, retrieve the current position, stop the sound channel and when you resume your sound, use the stored position as a start time for the play method. | The position is determined in milliseconds. So if you need to pause a sound, retrieve the current position, stop the sound channel and when you resume your sound, use the stored position as a start time for the play method. | ||
| Line 110: | Line 110: | ||
'''PREV.''': [[Introduction to Fonts]]<br/> | '''PREV.''': [[Introduction to Fonts]]<br/> | ||
'''NEXT''': [[Event system]] | '''NEXT''': [[Event system]] | ||
| + | |||
| + | |||
| + | {{GIDEROS IMPORTANT LINKS}} | ||
Latest revision as of 22:20, 18 November 2023
The Ultimate Guide to Gideros Studio
Playing sound and music
Introduction to sound system
The Sound class in Gideros lets you play back sound files of all kinds. Be it short sound effects like a gunshot or a 5-minute piece of music, it doesn’t matter. Under the hood, Gideros utilizes OpenAL for playing back WAV files and AVAudioPlayer to play back MP3 files.
The supported file formats are MP3 and WAV on iOS and Android (OGG via a plugin).
If you need to convert your sounds files to one of these formats, then try the open source software Audacity. It will help you convert your sound files in no time.
Regarding the performance, you should use .wav files for sound effects and .mp3 for background music. Here are the advantages and disadvantages of these:
- WAV files: Entire sound is loaded into memory. Consumes little CPU while playing. Suitable for simultaneously played sound effects.
- MP3 files: Sound is played by reading small chunks, therefore, consumes little memory. Consumes more CPU compared to WAV files. Suitable for background music/speech.
Playing a sound
Here is a sample to play a sound inside your app. It uses the play method of the Sound class:
-- Load a new sound and assign it to a variable
local yourSound = Sound.new("yourSoundFile.mp3")
-- Now play the sound
yourSound:play()
As you can see, it is very easy to play a sound effect or a music file. The play method of the Sound class has three optional parameters:
- startTime (number, default = 0)
- loop (number, default = 0)
- paused (boolean, default = false)
With the startTime, you can control the starting point in milliseconds, from where a sound is played back. The loop parameter will control if the sound will be played repeatedly for the given number of times. The paused parameter will tell Gideros if the sound should be paused upon creation (useful for SoundChannel). Here is a simple example that will play a sound starting from 200 milliseconds and repeat itself 5 times:
yourSound:play(200, 5)
If you want to let a sound play repeatedly, then just set the loop value to math.huge:
yourSound:play(0, math.huge)
Using sound channels
Playing back sounds inside your app is nice but sometimes you want to have a little bit more control over things. For this Gideros uses sound channels. How are they created or retrieved you might ask? Piece of cake! Whenever you play a sound, assign the returning value (the sound channel) to a variable. Like this:
local yourChannel = yourSound:play()
There is one event that will tell you when a sound channel has finished playing a sound file: Event.COMPLETE. Next is a small example on how the Event.COMPLETE event can be used:
-- Load a music file
local snd = Sound.new("DST-Psykick.mp3")
-- Start playing the music file and store the channel
local chan = snd:play()
-- Define the Event.COMPLETE function that is called
-- when the sound finishes playing
function onSoundComplete(event)
print ("Sound complete")
end
-- Add the event listener that is firing when the sound
-- finishes playing
chan:addEventListener(Event.COMPLETE,onSoundComplete)
Releasing a sound
You don’t have to release a sound manually. It will be collected once the app ends. But if you need to release a sound during the life of your app, then just set the corresponding channel to nil:
yourSound = nil
Note: If the sound is currently playing, the sound will be released after it finishes playing.
Stopping a sound
If you want to stop a playing sound, then use your sound channel and its stop method for it:
sndChannel:stop()
Getting length of a sound file
Sometimes you need to know how long a sound file is exactly. To determine the length of a sound file you can use the getLength method. Use it with your sound channel:
local sndLength = sndChannel:getLength()
After this line is executed, sndLength will hold the length of the sound in milliseconds.
Setting and getting the volume of a sound
Before you break some ears with loud sounds, you better give your users the possibility to control the volume of the sounds your app is playing. For this, there are two methods, setVolume, and getVolume. To get the volume of a sound, try this:
local volume = sndChannel:getVolume()
And to set the volume of a channel, use setVolume like this:
sndChannel:setVolume(0.5)
The volume levels ranging from 0.0 to 1.0. The later means maximum volume.
Getting the current position of a sound playing
When you need to pause a sound or display the current position of a sound playing, you need to determine the current position of a channel. For this use the getPosition method with your channel:
local currSndPos = sndChannel:getPosition()
The position is determined in milliseconds. So if you need to pause a sound, retrieve the current position, stop the sound channel and when you resume your sound, use the stored position as a start time for the play method.
PREV.: Introduction to Fonts
NEXT: Event system
