Metadata-Version: 2.4
Name: ovos-skill-white-noise
Version: 0.0.1
Summary: An ambient sound machine for OVOS - white/brown noise, rain, ocean waves, fan noise, looped for sleep or focus. A surprisingly common voice-assistant feature (Alexa/Google both have it) that's missing
Home-page: https://github.com/andlo/ovos-skill-white-noise
Author: Andreas Lorensen
Author-email: andlo@outlook.dk
License: GPL-3.0-or-later
Project-URL: Source, https://github.com/andlo/ovos-skill-white-noise
Project-URL: Bug Tracker, https://github.com/andlo/ovos-skill-white-noise/issues
Keywords: ovos skill voice assistant ambient sleep focus white noise relaxation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-python
Dynamic: summary

# <img src='icon.png' card_color='#808080' width='50' height='50' style='vertical-align:bottom'/> White Noise

An ambient noise machine for OVOS - "play white noise" for sleep or
focus. White, pink, and brown noise, **all generated**, not recorded.

[![Tests](https://github.com/andlo/ovos-skill-white-noise/actions/workflows/test.yml/badge.svg)](https://github.com/andlo/ovos-skill-white-noise/actions/workflows/test.yml)
[![PyPI version](https://img.shields.io/pypi/v/ovos-skill-white-noise.svg)](https://pypi.org/project/ovos-skill-white-noise/)

## Usage
```
"play white noise"
"play pink noise"
"start some background noise"
"stop the noise"
"spil hvid støj"          (Danish)
"stop støjen"             (Danish)
```

## Why no rain/ocean/fan sounds

The original brief mentioned rain and ocean waves too. Those need
genuinely **loopable recordings** - a hard seam or click at the loop
point would be very noticeable in a sustained ambient track, a
stricter sourcing requirement than the short one-shot clips
[ovos-skill-sound-like](https://github.com/andlo/ovos-skill-sound-like)
uses. White/pink/brown noise sidesteps the problem entirely: noise
has no coherent waveform pattern for the ear to lock onto, so a
generated clip looping back to its own start is inherently seamless.
Rain/ocean are a real future possibility, but need actual recordings
sourced and vetted for clean looping - not built here.

## How the noise is generated

- **White**: uniform random samples (flat spectrum).
- **Pink**: [Paul Kellet's economy IIR filter](https://www.firstpr.com.au/dsp/pink-noise/)
  approximation (1/f spectrum) - a well-known, publicly documented
  DSP technique, not sourced from any particular library or artist.
- **Brown/red**: a clamped random walk (1/f² spectrum).

All three use a fixed random seed, so regenerating a given noise type
produces byte-identical audio - deterministic, same as every other
generated sound in this project family (clicks, tones, drum hits),
even though the underlying content is "random".

## Why "stop" doesn't stop instantly

Same underlying reason as
[ovos-skill-tuning-fork](https://github.com/andlo/ovos-skill-tuning-fork):
`play_audio()` has no reliable way to interrupt an already-playing
sound. Noise loops by repeatedly re-triggering a 20-second generated
clip - "stop" prevents the *next* clip from starting, but the clip
already playing rings out to its natural end. Worst case, that's up
to 20 seconds - noticeably longer than the metronome/rhythm-box's
"before the next beat" stop latency, and disclosed rather than
glossed over.

## Install
```bash
pip install ovos-skill-white-noise
```

## Development

See [DEVELOPMENT.md](DEVELOPMENT.md).

## Category
**Utility**

## Tags
#ambient #sleep #focus #white-noise #relaxation
