Documentation
¶
Overview ¶
Package sound provides optional audio notifications for run-lifecycle events.
Playback is opt-in via the sound section in .productize/config.toml and is disabled by default. A Noop player is used whenever the feature flag is off or the platform is not supported, so callers never need to special-case "sound is turned off".
Index ¶
Constants ¶
const ( PresetGlass = "glass" PresetBasso = "basso" PresetPing = "ping" PresetHero = "hero" PresetFunk = "funk" PresetTink = "tink" PresetSubmarine = "submarine" )
preset names accepted in config.toml. Absolute paths bypass preset lookup.
Variables ¶
var ErrEmptySound = errors.New("sound: empty sound name")
ErrEmptySound indicates the caller passed an empty sound identifier.
var ErrUnsupported = errors.New("sound: unsupported platform")
ErrUnsupported indicates the running platform cannot play sounds.
Functions ¶
func KnownPresets ¶
func KnownPresets() []string
KnownPresets lists every preset name the resolver understands. The list is exposed so the CLI / docs can surface valid values without re-declaring them.
func Notify ¶
Notify plays the configured sound for the given lifecycle event kind and blocks until the underlying player returns. Notify is the only API the run pipelines use: it runs on the caller's goroutine so the sound is guaranteed to finish before run cleanup tears down state.
The parent context is detached via context.WithoutCancel before playback starts. This is deliberate: on run.failed and run.cancelled the caller passes a ctx that is already done, and a canceled exec.CommandContext would immediately kill afplay/paplay so the failure sound would never be audible. A bounded playbackTimeout prevents a hung player from delaying run shutdown indefinitely.
Unrecognized kinds and empty preset configurations are silent no-ops. Playback errors are logged at debug and never bubble back to the caller — a missing system sound must not break a successful run.
func ResolvePath ¶
ResolvePath maps a preset name or filesystem path to a concrete file that the platform player can consume. Absolute paths are returned verbatim. Unknown presets produce a descriptive error so users see typos early.
Types ¶
type Config ¶
Config binds a Player to per-event-kind preset names. Both presets and absolute filesystem paths are accepted; an empty string for a given kind disables playback for that kind.
type Noop ¶
type Noop struct{}
Noop is the zero-cost player used when sound is disabled or unsupported.
Source Files