docs » hs.sound

Load/play/manipulate sound files

API Overview

Functions - API calls offered directly by the extension

getAudioEffectNames
soundFileTypes
soundTypes
systemSounds

Constructors - API calls which return an object, typically one that offers API methods

getByFile
getByName

Methods - API calls which can only be made on an object returned by a constructor

currentTime
device
duration
isPlaying
loopSound
name
pause
play
resume
setCallback
stop
stopOnReload
volume

API Documentation

Functions

getAudioEffectNames

Signature	`hs.sound.getAudioEffectNames() -> table`
Type	Function
Description	Gets a table of installed Audio Units Effect names.
Parameters	None
Returns	A table containing the names of all installed Audio Units Effects.
Notes	Example usage: `hs.inspect(hs.audiounit.getAudioEffectNames())`
Source	extensions/sound/internal.m

soundFileTypes

Signature	`hs.sound.soundFileTypes() -> table`
Type	Function
Description	Gets the supported sound file types
Parameters	None
Returns	A table containing the sound file filename extensions that are supported by the system
Notes	This function is unlikely to be tremendously useful, as filename extensions are essentially meaningless. The data returned by `hs.sound.soundTypes()` is far more valuable
Source	extensions/sound/internal.m

soundTypes

Signature	`hs.sound.soundTypes() -> table`
Type	Function
Description	Gets the supported UTI sound file formats
Parameters	None
Returns	A table containing the UTI sound formats that are supported by the system
Source	extensions/sound/internal.m

systemSounds

Signature	`hs.sound.systemSounds() -> table`
Type	Function
Description	Gets a table of available system sounds
Parameters	None
Returns	A table containing all of the available sound files (i.e. those found in ~/Library/Sounds, /Library/Sounds, /Network/Library/Sounds and /System/Library/Sounds)
Notes	The sounds listed by this function can be loaded using `hs.sound.getByName()`
Source	extensions/sound/internal.m

Constructors

getByFile

Signature	`hs.sound.getByFile(path) -> sound or nil`
Type	Constructor
Description	Creates an `hs.sound` object from a file
Parameters	path - A string containing the path to a sound file
Returns	An `hs.sound` object or nil if the file could not be loaded
Source	extensions/sound/internal.m

getByName

Signature	`hs.sound.getByName(name) -> sound or nil`
Type	Constructor
Description	Creates an `hs.sound` object from a named sound
Parameters	name - A string containing the name of a sound
Returns	An `hs.sound` object or nil if no matching sound could be found
Notes	Sounds can only be loaded by name if they are System Sounds (i.e. those found in ~/Library/Sounds, /Library/Sounds, /Network/Library/Sounds and /System/Library/Sounds) or are sound files that have previously been loaded and named
Source	extensions/sound/internal.m

Methods

currentTime

Signature	`hs.sound:currentTime([seekTime]) -> soundObject \| seconds`
Type	Method
Description	Get or set the current seek offset within an `hs.sound` object.
Parameters	seekTime - An optional number of seconds to seek to within the sound object
Returns	If a parameter is provided, returns the sound object; otherwise returns the current position.
Source	extensions/sound/internal.m

device

Signature	`hs.sound:device([deviceUID]) -> soundObject \| UID string`
Type	Method
Description	Get or set the playback device to use for an `hs.sound` object
Parameters	deviceUID - An optional string containing the UID of an `hs.audiodevice` object to use for playback of this sound. Use an explicit nil to use the system's default device
Returns	If a parameter is provided, returns the sound object; otherwise returns the current setting.
Notes	To obtain the UID of a sound device, see `hs.audiodevice:uid()`
Source	extensions/sound/internal.m

duration

Signature	`hs.sound:duration() -> seconds`
Type	Method
Description	Gets the length of an `hs.sound` object
Parameters	None
Returns	A number containing the length of the sound, in seconds
Source	extensions/sound/internal.m

isPlaying

Signature	`hs.sound:isPlaying() -> bool`
Type	Method
Description	Gets the current playback state of an `hs.sound` object
Parameters	None
Returns	A boolean, true if the sound is currently playing, otherwise false
Source	extensions/sound/internal.m

loopSound

Signature	`hs.sound:loopSound([loop]) -> soundObject \| bool`
Type	Method
Description	Get or set the looping behaviour of an `hs.sound` object
Parameters	loop - An optional boolean, true to loop playback, false to not loop
Returns	If a parameter is provided, returns the sound object; otherwise returns the current setting.
Notes	If you have registered a callback function for completion of a sound's playback, it will not be called when the sound loops
Source	extensions/sound/internal.m

name

Signature	`hs.sound:name([soundName]) -> soundObject \| name string`
Type	Method
Description	Get or set the name of an `hs.sound` object
Parameters	soundName - An optional string to use as the name of the object; use an explicit nil to remove the name
Returns	If a parameter is provided, returns the sound object; otherwise returns the current setting.
Notes	If remove the sound name by specifying `nil`, the sound will automatically be set to stop when Hammerspoon is reloaded.
Source	extensions/sound/internal.m

pause

Signature	`hs.sound:pause() -> soundObject \| bool`
Type	Method
Description	Pauses an `hs.sound` object
Parameters	None
Returns	The `hs.sound` object if the command was successful, otherwise false.
Source	extensions/sound/internal.m

play

Signature	`hs.sound:play() -> soundObject \| bool`
Type	Method
Description	Plays an `hs.sound` object
Parameters	None
Returns	The `hs.sound` object if the command was successful, otherwise false.
Source	extensions/sound/internal.m

resume

Signature	`hs.sound:resume() -> soundObject \| bool`
Type	Method
Description	Resumes playing a paused `hs.sound` object
Parameters	None
Returns	The `hs.sound` object if the command was successful, otherwise false.
Source	extensions/sound/internal.m

setCallback

Signature	`hs.sound:setCallback(function) -> soundObject`
Type	Method
Description	Set or remove the callback for receiving completion notification for the sound object.
Parameters	function - A function which should be called when the sound completes playing. Specify an explicit nil to remove the callback function.
Returns	the sound object
Notes	the callback function should accept two parameters and return none. The parameters passed to the callback function are: state - a boolean flag indicating if the sound completed playing. Returns true if playback completes properly, or false if a decoding error occurs or if the sound is stopped early with `hs.sound:stop`. sound - the soundObject userdata
Source	extensions/sound/internal.m

stop

Signature	`hs.sound:stop() -> soundObject \| bool`
Type	Method
Description	Stops playing an `hs.sound` object
Parameters	None
Returns	The `hs.sound` object if the command was successful, otherwise false.
Source	extensions/sound/internal.m

stopOnReload

Signature	`hs.sound:stopOnReload([stopOnReload]) -> soundObject \| bool`
Type	Method
Description	Get or set whether a sound should be stopped when Hammerspoon reloads its configuration
Parameters	stopOnReload - An optional boolean, true to stop playback when Hammerspoon reloads its config, false to continue playback regardless. Defaults to true.
Returns	If a parameter is provided, returns the sound object; otherwise returns the current setting.
Notes	This method can only be used on a named `hs.sound` object, see `hs.sound:name()`
Source	extensions/sound/internal.m

volume

Signature	`hs.sound:volume([level]) -> soundObject \| number`
Type	Method
Description	Get or set the playback volume of an `hs.sound` object
Parameters	level - A number between 0.0 and 1.0, representing the volume of the sound object relative to the current system volume
Returns	If a parameter is provided, returns the sound object; otherwise returns the current value.
Source	extensions/sound/internal.m