Skip to content
This repository has been archived by the owner on Jun 9, 2023. It is now read-only.

Latest commit

 

History

History
198 lines (172 loc) · 18.6 KB

hs.sound.md

File metadata and controls

198 lines (172 loc) · 18.6 KB
Raw

docs » 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())

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

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

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

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

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

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.
|

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

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

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

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
|

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.
|

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.
|

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.
|

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.
|

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

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.
|

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

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.
|