Constructor
Sound(data: love.SoundData, settings: (Assets.sound_settings)?)
Arguments:
| data: love.SoundData | Contains raw audio samples. You can not play SoundData back directly. You must wrap a Source object around it. |
| settings: (Assets.sound_settings)? | Settings for a sound asset, paired with the actual sound data as a .json file. |
Methods
Sound:clone()
Creates an identical copy of the Sound in the stopped state.
Static Sounds will use significantly less memory and take much less time to be created if Sound:clone is used to create them instead of love.audio.newSource, so this method should be preferred when making multiple Sounds which play the same sound.
Returns:
| 1: Sound |
Sound:getAirAbsorption()
Gets the amount of air absorption applied to the Sound.
By default the value is set to 0 which means that air absorption effects are disabled. A value of 1 will apply high frequency attenuation to the Sound at a rate of 0.05 dB per meter.
Returns:
| 1: number |
Sound:getAttenuationDistances()
Gets the reference and maximum attenuation distances of the Sound. The values, combined with the current DistanceModel, affect how the Sound's volume attenuates based on distance from the listener.
Returns:
| 1: number | |
| 2: number |
Sound:getChannelCount()
Gets the number of channels in the Sound. Only 1-channel (mono) Sounds can use directional and positional effects.
Returns:
| 1: number |
Sound:getCone()
Gets the Sound's directional volume cones. Together with Sound:setDirection, the cone angles allow for the Sound's volume to vary depending on its direction.
Returns:
| 1: number | |
| 2: number | |
| 3: number |
Sound:getDuration(unit: ("samples"|"seconds")?)
Gets the duration of the Sound. For streaming Sounds it may not always be sample-accurate, and may return -1 if the duration cannot be determined at all.
--
-- Units that represent time.
--
--
-- [Open in Browser](https://love2d.org/wiki/TimeUnit)
--
unit:
| "seconds" -- Regular seconds.
| "samples" -- Audio samples.
Arguments:
| unit: ("samples"|"seconds")? | The time unit for the return value. (Defaults to 'seconds'.) |
Returns:
| 1: number |
Sound:getEffect(name: string, filtersettings: table?)
Gets the filter settings associated to a specific effect.
This function returns nil if the effect was applied with no filter settings associated to it.
Arguments:
| name: string | The name of the effect. |
| filtersettings: table? | An optional empty table that will be filled with the filter settings. (Defaults to {}.) |
Returns:
| 1: table |
Sound:getFreeBufferCount()
Gets the number of free buffer slots in a queueable Sound. If the queueable Sound is playing, this value will increase up to the amount the Sound was created with. If the queueable Sound is stopped, it will process all of its internal buffers first, in which case this function will always return the amount it was created with.
Returns:
| 1: number |
Sound:getType()
Gets the type of the Sound.
--
-- Types of audio sources.
--
-- A good rule of thumb is to use stream for music files and static for all short sound effects. Basically, you want to avoid loading large files into memory at once.
--
--
-- [Open in Browser](https://love2d.org/wiki/SourceType)
--
return #1:
| "static" -- The whole audio is decoded.
| "stream" -- The audio is decoded in chunks when needed.
| "queue" -- The audio must be manually queued by the user.
Returns:
| 1: "queue"|"static"|"stream" |
Sound:isRelative()
Gets whether the Sound's position, velocity, direction, and cone angles are relative to the listener.
Returns:
| 1: boolean |
Sound:pause()
Pauses the Sound.
Sound:queue(sounddata: love.SoundData)
Queues SoundData for playback in a queueable Sound.
This method requires the Sound to be created via love.audio.newQueueableSource.
Arguments:
| sounddata: love.SoundData | The data to queue. The SoundData's sample rate, bit depth, and channel count must match the Sound's. |
Returns:
| 1: boolean |
Sound:seek(offset: number, unit: ("samples"|"seconds")?)
Sets the currently playing position of the Sound.
--
-- Units that represent time.
--
--
-- [Open in Browser](https://love2d.org/wiki/TimeUnit)
--
unit:
| "seconds" -- Regular seconds.
| "samples" -- Audio samples.
Arguments:
| offset: number | The position to seek to. |
| unit: ("samples"|"seconds")? | The unit of the position value. (Defaults to 'seconds'.) |
Sound:setAirAbsorption(amount: number)
Sets the amount of air absorption applied to the Sound.
By default the value is set to 0 which means that air absorption effects are disabled. A value of 1 will apply high frequency attenuation to the Sound at a rate of 0.05 dB per meter.
Air absorption can simulate sound transmission through foggy air, dry air, smoky atmosphere, etc. It can be used to simulate different atmospheric conditions within different locations in an area.
Arguments:
| amount: number | The amount of air absorption applied to the Sound. Must be between 0 and 10. |
Sound:setAttenuationDistances(ref: number, max: number)
Sets the reference and maximum attenuation distances of the Sound. The parameters, combined with the current DistanceModel, affect how the Sound's volume attenuates based on distance.
Distance attenuation is only applicable to Sounds based on mono (rather than stereo) audio.
Arguments:
| ref: number | The new reference attenuation distance. If the current DistanceModel is clamped, this is the minimum attenuation distance. |
| max: number | The new maximum attenuation distance. |
Sound:setCone(innerAngle: number, outerAngle: number, outerVolume: number?)
Sets the Sound's directional volume cones. Together with Sound:setDirection, the cone angles allow for the Sound's volume to vary depending on its direction.
Arguments:
| innerAngle: number | The inner angle from the Sound's direction, in radians. The Sound will play at normal volume if the listener is inside the cone defined by this angle. |
| outerAngle: number | The outer angle from the Sound's direction, in radians. The Sound will play at a volume between the normal and outer volumes, if the listener is in between the cones defined by the inner and outer angles. |
| outerVolume: number? | The Sound's volume when the listener is outside both the inner and outer cone angles. (Defaults to 0.) |
Sound:setDirection(x: number, y: number, z: number)
Sets the direction vector of the Sound. A zero vector makes the source non-directional.
Arguments:
| x: number | The X part of the direction vector. |
| y: number | The Y part of the direction vector. |
| z: number | The Z part of the direction vector. |
Sound:setEffect(name: string, enable: boolean?)
Applies an audio effect to the Sound.
The effect must have been previously defined using love.audio.setEffect.
Arguments:
| name: string | The name of the effect previously set up with love.audio.setEffect. |
| enable: boolean? | If false and the given effect name was previously enabled on this Sound, disables the effect. (Defaults to true.) |
Returns:
| 1: boolean |
Sound:setFilter(settings: table?)
Sets a low-pass, high-pass, or band-pass filter to apply when playing the Sound.
Arguments:
| settings: table? | The filter settings to use for this Sound, with the following fields: |
Returns:
| 1: boolean |
Sound:setLooping(loop: boolean)
Sets whether the Sound should loop.
Arguments:
| loop: boolean | True if the source should loop, false otherwise. |
Sound:setPitch(pitch: number)
Sets the pitch of the Sound.
Arguments:
| pitch: number | Calculated with regard to 1 being the base pitch. Each reduction by 50 percent equals a pitch shift of -12 semitones (one octave reduction). Each doubling equals a pitch shift of 12 semitones (one octave increase). Zero is not a legal value. |
Sound:setPosition(x: number, y: number, z: number)
Sets the position of the Sound. Please note that this only works for mono (i.e. non-stereo) sound files!
Arguments:
| x: number | The X position of the Sound. |
| y: number | The Y position of the Sound. |
| z: number | The Z position of the Sound. |
Sound:setRelative(enable: boolean?)
Sets whether the Sound's position, velocity, direction, and cone angles are relative to the listener, or absolute.
By default, all sources are absolute and therefore relative to the origin of love's coordinate system 0, 0. Only absolute sources are affected by the position of the listener. Please note that positional audio only works for mono (i.e. non-stereo) sources.
Arguments:
| enable: boolean? | True to make the position, velocity, direction and cone angles relative to the listener, false to make them absolute. (Defaults to false.) |
Sound:setRolloff(rolloff: number)
Sets the rolloff factor which affects the strength of the used distance attenuation.
Extended information and detailed formulas can be found in the chapter '3.4. Attenuation By Distance' of OpenAL 1.1 specification.
Arguments:
| rolloff: number | The new rolloff factor. |
Sound:setVelocity(x: number, y: number, z: number)
Sets the velocity of the Sound.
This does '''not''' change the position of the Sound, but lets the application know how it has to calculate the doppler effect.
Arguments:
| x: number | The X part of the velocity vector. |
| y: number | The Y part of the velocity vector. |
| z: number | The Z part of the velocity vector. |
Sound:setVolume(volume: number)
Sets the current volume of the Sound.
Arguments:
| volume: number | The volume for a Sound, where 1.0 is normal volume. Volume cannot be raised above 1.0. |
Sound:setVolumeLimits(min: number, max: number)
Sets the volume limits of the source. The limits have to be numbers from 0 to 1.
Arguments:
| min: number | The minimum volume. |
| max: number | The maximum volume. |
Sound:stop()
Stops a Sound.
Sound:tell(unit: ("samples"|"seconds")?)
Gets the currently playing position of the Sound.
--
-- Units that represent time.
--
--
-- [Open in Browser](https://love2d.org/wiki/TimeUnit)
--
unit:
| "seconds" -- Regular seconds.
| "samples" -- Audio samples.
Arguments:
| unit: ("samples"|"seconds")? | The type of unit for the return value. (Defaults to 'seconds'.) |
Returns:
| 1: number |
Fields
Sound.settings: Assets.sound_settings
Settings for a sound asset, paired with the actual sound data as a .json file.
Undocumented
Sound.source: love.Source
A Source represents audio you can play back.
You can do interesting things with Sources, like set the volume, pitch, and its position relative to the listener. Please note that positional audio only works for mono (i.e. non-stereo) sources.
The Source controls (play/pause/stop) act according to the following state table.