docs » hs.sound

Gets a table of installed Audio Units Effect names.

• None

• A table containing the names of all installed Audio Units Effects.

• Example usage: hs.inspect(hs.audiounit.getAudioEffectNames())

Gets the supported sound file types

• None

• A table containing the sound file filename extensions that are supported by the system

• 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

Gets the supported UTI sound file formats

• None

• A table containing the UTI sound formats that are supported by the system

Gets a table of available system sounds

• None

• 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)

• The sounds listed by this function can be loaded using hs.sound.getByName()

Creates an hs.sound object from a file

• path - A string containing the path to a sound file

• An hs.sound object or nil if the file could not be loaded

Creates an hs.sound object from a named sound

• name - A string containing the name of a sound

• An hs.sound object or nil if no matching sound could be found

• 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

Get or set the current seek offset within an hs.sound object.

• seekTime - An optional number of seconds to seek to within the sound object

• If a parameter is provided, returns the sound object; otherwise returns the current position.

Get or set the playback device to use for an hs.sound object

• 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

• If a parameter is provided, returns the sound object; otherwise returns the current setting.

• To obtain the UID of a sound device, see hs.audiodevice:uid()

Gets the length of an hs.sound object

• None

• A number containing the length of the sound, in seconds

Gets the current playback state of an hs.sound object

• None

• A boolean, true if the sound is currently playing, otherwise false

Get or set the looping behaviour of an hs.sound object

• loop - An optional boolean, true to loop playback, false to not loop

• If a parameter is provided, returns the sound object; otherwise returns the current setting.

• If you have registered a callback function for completion of a sound's playback, it will not be called when the sound loops

Get or set the name of an hs.sound object

• soundName - An optional string to use as the name of the object; use an explicit nil to remove the name

• If a parameter is provided, returns the sound object; otherwise returns the current setting.

• If remove the sound name by specifying nil, the sound will automatically be set to stop when Hammerspoon is reloaded.

Pauses an hs.sound object

• None

• The hs.sound object if the command was successful, otherwise false.

Plays an hs.sound object

• None

• The hs.sound object if the command was successful, otherwise false.

Resumes playing a paused hs.sound object

• None

• The hs.sound object if the command was successful, otherwise false.

Set or remove the callback for receiving completion notification for the sound object.

• function - A function which should be called when the sound completes playing. Specify an explicit nil to remove the callback function.

• the sound object

• 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

Stops playing an hs.sound object

• None

• The hs.sound object if the command was successful, otherwise false.

Get or set whether a sound should be stopped when Hammerspoon reloads its configuration

• stopOnReload - An optional boolean, true to stop playback when Hammerspoon reloads its config, false to continue playback regardless. Defaults to true.

• If a parameter is provided, returns the sound object; otherwise returns the current setting.

• This method can only be used on a named hs.sound object, see hs.sound:name()

Get or set the playback volume of an hs.sound object

• level - A number between 0.0 and 1.0, representing the volume of the sound object relative to the current system volume

• If a parameter is provided, returns the sound object; otherwise returns the current value.