websfx/dist/index.d.cts

Play synthesized UI sound effects using the Web Audio API

//#region src/types.d.ts
/**
 * Options accepted by every sound effect.
 */
interface SoundOptions {
  /**
   * Volume multiplier for this call from `0` to `1`.
   *
   * Multiplied with the master volume from `configure()`.
   *
   * @defaultValue 1
   */
  volume?: number;
  /**
   * Pitch multiplier applied to all frequencies in the sound.
   *
   * For example, `2` plays the sound one octave higher.
   *
   * @defaultValue 1
   */
  pitch?: number;
}
/**
 * Options accepted by the `beep` sound.
 */
interface BeepOptions extends SoundOptions {
  /**
   * Frequency of the tone in hertz.
   *
   * @defaultValue 880
   */
  frequency?: number;
}
/**
 * Global sound configuration managed by `configure()`.
 */
interface Config {
  /**
   * Master volume from `0` to `1`. Set to `0` to mute.
   */
  volume: number;
}
//#endregion
//#region src/context.d.ts
/**
 * Reads or updates the global sound configuration.
 *
 * Called with a partial configuration it applies the update first. Always
 * returns the current configuration. Set `volume` to `0` to mute.
 *
 * @example
 * ```ts
 * configure({ volume: 0.5 });
 * configure({ volume: 0 }); // mute
 * const { volume } = configure();
 * ```
 *
 * @param options - Partial configuration to merge.
 * @returns The current configuration.
 */
export declare function configure(options?: Partial<Config>): Readonly<Config>;
//#endregion
//#region src/sounds.d.ts
/**
 * Plays a sharp click, e.g. for buttons and links.
 *
 * @param options - Per-call sound options.
 */
export declare function click(options?: SoundOptions): void;
/**
 * Plays a soft tick for pointer hover states.
 *
 * @param options - Per-call sound options.
 */
export declare function hover(options?: SoundOptions): void;
/**
 * Plays a subtle cue for keyboard focus.
 *
 * @param options - Per-call sound options.
 */
export declare function focus(options?: SoundOptions): void;
/**
 * Plays a descending tone for a pointer or key press.
 *
 * @param options - Per-call sound options.
 */
export declare function press(options?: SoundOptions): void;
/**
 * Plays a rising tone for a pointer or key release.
 *
 * @param options - Per-call sound options.
 */
export declare function release(options?: SoundOptions): void;
/**
 * Plays a sustained rising tone for long press gestures.
 *
 * @param options - Per-call sound options.
 */
export declare function longPress(options?: SoundOptions): void;
/**
 * Plays two quick clicks for double click gestures.
 *
 * @param options - Per-call sound options.
 */
export declare function doubleClick(options?: SoundOptions): void;
/**
 * Plays a soft friction tick for drag gestures.
 *
 * @param options - Per-call sound options.
 */
export declare function drag(options?: SoundOptions): void;
/**
 * Plays a low thud for drop gestures.
 *
 * @param options - Per-call sound options.
 */
export declare function drop(options?: SoundOptions): void;
/**
 * Plays a keystroke tap for text input.
 *
 * @param options - Per-call sound options.
 */
export declare function type(options?: SoundOptions): void;
/**
 * Plays a rising two-note chime for selection.
 *
 * @param options - Per-call sound options.
 */
export declare function select(options?: SoundOptions): void;
/**
 * Plays a falling two-note chime for deselection.
 *
 * @param options - Per-call sound options.
 */
export declare function deselect(options?: SoundOptions): void;
/**
 * Plays a rising sweep for opening UI such as modals and popovers.
 *
 * @param options - Per-call sound options.
 */
export declare function open(options?: SoundOptions): void;
/**
 * Plays a falling sweep for closing UI such as modals and popovers.
 *
 * @param options - Per-call sound options.
 */
export declare function close(options?: SoundOptions): void;
/**
 * Plays a falling swoosh for navigating back.
 *
 * @param options - Per-call sound options.
 */
export declare function back(options?: SoundOptions): void;
/**
 * Plays a rising swoosh for navigating forward.
 *
 * @param options - Per-call sound options.
 */
export declare function forward(options?: SoundOptions): void;
/**
 * Plays a plain sine beep.
 *
 * @example
 * ```ts
 * beep();
 * beep({ frequency: 440 });
 * ```
 *
 * @param options - Per-call sound options and tone frequency.
 */
export declare function beep(options?: BeepOptions): void;
/**
 * Plays a rising major arpeggio for successful operations.
 *
 * @param options - Per-call sound options.
 */
export declare function success(options?: SoundOptions): void;
/**
 * Plays a low two-note buzz for failed operations.
 *
 * @param options - Per-call sound options.
 */
export declare function error(options?: SoundOptions): void;
/**
 * Plays an alternating two-tone alert for warnings.
 *
 * @param options - Per-call sound options.
 */
export declare function warning(options?: SoundOptions): void;
/**
 * Plays a gentle descending two-note tone for cancelled operations.
 *
 * @param options - Per-call sound options.
 */
export declare function cancel(options?: SoundOptions): void;
/**
 * Plays a two-note chime for notifications.
 *
 * @param options - Per-call sound options.
 */
export declare function notification(options?: SoundOptions): void;
/**
 * Plays a rising two-note blip for copy operations.
 *
 * @param options - Per-call sound options.
 */
export declare function copy(options?: SoundOptions): void;
/**
 * Plays a soft falling tone for paste operations.
 *
 * @param options - Per-call sound options.
 */
export declare function paste(options?: SoundOptions): void;
/**
 * Plays a descending blip for destructive remove actions.
 *
 * @param options - Per-call sound options.
 */
export declare function remove(options?: SoundOptions): void;
/**
 * Plays a playful rising bloop for reactions.
 *
 * @param options - Per-call sound options.
 */
export declare function reaction(options?: SoundOptions): void;
//#endregion
export type { BeepOptions, Config, SoundOptions };
//# sourceMappingURL=index.d.cts.map