W3cubDocs

/Hammerspoon

hs.sound

Load/play/manipulate sound files

API Overview

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/libsound.m line 62
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/libsound.m line 200
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/libsound.m line 184
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/libsound.m line 150

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/libsound.m line 128
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/libsound.m line 103

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/libsound.m line 435
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/libsound.m line 400
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/libsound.m line 457
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/libsound.m line 496
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/libsound.m line 316
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/libsound.m line 370
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/libsound.m line 253
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/libsound.m line 228
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/libsound.m line 274
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/libsound.m line 513
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/libsound.m line 295
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/libsound.m line 341
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/libsound.m line 474

© 2014–2017 Hammerspoon contributors
Licensed under the MIT License.
https://www.hammerspoon.org/docs/hs.sound.html