Sound

Free · MIT

A CSS custom property's value as the text it names: quotes removed, or the inside of url(…). Empty when unset.

Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0, 2.2.0 and 2.3.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

It's types and helpers, listed below.

Install

With the Candor CLI

Open the starter in StackBlitz

Opens the free starter app in StackBlitz, in your browser, on stackblitz.com. Sound isn’t added for you: run npx candor-ui add sound in its terminal. The starter’s agent needs an Anthropic API key to chat; without one it shows the components only.

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/sound

Brings in: tokens

Functions

soundString(raw: string)

readSoundVolume(event: SoundEvent, element?: Element | undefined)

How loud event is, 0 to 1: the global --cd-sound-volume times the event's own, each 1 when unset. 1 on the server.

readSoundToken(event: SoundEvent, element?: Element | undefined)

The brand's sound for event, read from the computed style of element (the document's root when left out), or undefined when the brand names none, or on the server.

mayPlay(event: SoundEvent, last: Partial<Record<SoundEvent, number>>, now: number, burstMs = 400)

Whether a play at now is allowed, given when each event last played and when anything last played: the same event waits soundCoalesceMs after it played, and any sound in the same instant (a burst) is the one already playing. Pure; the caller keeps the clock.

Values

soundEvents

Every event, in the order the settings control lists them.

readonly SoundEvent[]

defaultSoundEvents

The events a sound is offered for once the person turns sound on; reply and silent stay off until they pick them.

readonly SoundEvent[]

maxSoundSeconds

The longest a sound may be, in seconds. theme check measures what it can read.

1.5

soundCoalesceMs

The least time between two plays of the same event, in milliseconds. A burst plays once.

3000

Types

SoundEvent: The five things the app may make a sound for. A closed list: `useAttention` plays each for the `AttentionKind` of the same name (`needs-you` for `approval`).; "needs-you" | "finished" | "failed" | "reply" | "silent"
SoundToken: A sound as the brand names it: where the file is, an optional Ogg alternative, and how loud (0 to 1).; { src: string; ogg?: string | undefined; volume: number }