gw-sonification
Audio sonifications of gravitational-wave events from the LIGO/Virgo/KAGRA detectors. Strain data is downloaded from GWOSC, whitened, bandpassed, and written as a WAV file. A matching waveform template (generated via PyCBC) can be produced alongside it.
Installation
pip install -e . # core (strain data only)
pip install -e ".[waveform]" # + pycbc for waveform templates
pip install -e ".[waveform,dev]" # + dev tools (pytest, ruff)
The package exposes a sonify command-line tool and a Python API.
Command-line usage
Sonify a single event
# Sonified strain + waveform template, into the current directory
sonify event GW150914
# All standard variants (base + pitch-shifted by one octave)
sonify event GW150914 --all-variants
# Specific detector, custom pitch shift, custom output directory
sonify event GW190521_030229 --detector L1 --pitch-shift 7 --output-dir ./audio
# Skip generating the waveform template
sonify event GW150914 --all-variants --no-waveform
# Skip files that already exist
sonify event GW150914 --all-variants --skip-existing
# Use a local catalog JSON for event parameters (needed for accurate waveforms)
sonify event GW150914 --catalog gwtc4-all.json --all-variants
Batch-process a catalog
# Process all events in a local catalog JSON, skipping existing files
sonify batch --catalog gwtc4-all.json --output-dir ./audio
# Process only specific events
sonify batch --catalog gwtc4-all.json -e GW150914 -e GW170817
# Use the live GWOSC API as the catalog source
sonify batch --catalog gwosc --output-dir ./audio --no-waveform
# No pitch-shift variants
sonify batch --catalog gwtc4-all.json --no-all-variants
Check progress
sonify status ./audio # summary count
sonify status ./audio --show-complete # list complete events too
Output file naming
All output files follow a consistent convention:
{event_name}-{detector}-{type}[-{effect}].wav
| Component | Values |
|---|---|
event_name |
GWOSC name, e.g. GW150914 |
detector |
H1, L1, or V1 |
type |
sonified or waveform |
effect |
transpose, stretched, … (optional) |
Examples:
GW150914-H1-sonified.wav
GW150914-H1-sonified-transpose.wav
GW150914-H1-waveform.wav
GW150914-H1-waveform-transpose.wav
Python API
from sonification import Event, Waveform
from sonification.effects import PitchShift, TimeStretch
# Strain data
ev = Event("GW150914")
ev.sonify(output_dir="./audio", effects=[PitchShift(12)])
# Force a specific detector
ev = Event("GW170817", detector="L1")
ev.sonify("./audio")
# Waveform template from a catalog
from sonification.catalog import JSONCatalog
cat = JSONCatalog("gwtc4-all.json")
params = cat.get_event("GW150914")
wf = Waveform.from_event(params)
wf.sonify("GW150914", "H1", output_dir="./audio", effects=[PitchShift(12)])
# Custom waveform parameters
wf = Waveform({"mass1": 36.0, "mass2": 29.0, "spin1z": 0.3})
wf.sonify("GW150914", "H1", "./audio")
Extending the package
Custom catalog providers
Implement CatalogProvider to plug in a new data source:
from sonification.catalog import CatalogProvider, EventParameters
class MyCatalog(CatalogProvider):
def get_event(self, name: str) -> EventParameters:
# fetch from your database / API / file
return EventParameters(name=name, gps=..., detectors=["H1"])
def list_events(self) -> list[str]:
return [...]
# Use it anywhere a catalog is accepted
ev = Event("GW150914", catalog=MyCatalog())
Custom audio effects
Implement AudioEffect to add new post-processing steps:
import numpy as np
from sonification.effects import AudioEffect
class Reverse(AudioEffect):
"""Play the audio backwards."""
@property
def name_suffix(self) -> str:
return "reversed"
def apply(self, data: np.ndarray, sample_rate: int) -> np.ndarray:
return data[::-1].copy()
# Pass to sonify()
ev = Event("GW150914")
ev.sonify("./audio", effects=[Reverse()])
# writes: GW150914-H1-sonified.wav
# GW150914-H1-sonified-reversed.wav
Multiple effects can be chained — each produces its own output file:
from sonification.effects import PitchShift, TimeStretch
ev.sonify("./audio", effects=[PitchShift(12), TimeStretch(0.5)])
# writes: GW150914-H1-sonified.wav
# GW150914-H1-sonified-transpose.wav
# GW150914-H1-sonified-stretched.wav
Processing pipeline
For strain data (Event):
- Download 36 s of open strain data from GWOSC (cached locally).
- Detrend and apply a Tukey taper.
- Whiten using a 4 s FFT window with 2 s overlap.
- Bandpass filter: 30–400 Hz.
- Crop to a 32 s window centred 2 s after merger.
- Normalise to float32 in [−1, 1] and write as 16-bit PCM WAV.
- Apply each requested audio effect and write additional files.
For waveform templates (Waveform):
- Generate a time-domain
IMRPhenomXPHMwaveform via PyCBC. - Extract a 4 s window around the merger.
- Normalise and write as above.
Data
Strain data is downloaded from GWOSC and cached by gwpy.
Waveform templates use the IMRPhenomXPHM approximant from
PyCBC.
Metadata
Release files for gw-sonification 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gw_sonification-0.1.0.tar.gz | 15.7 kB | With provenance | Details for gw_sonification-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gw_sonification-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for gw_sonification-0.1.0-py3-none-any.whl |
Total release size: 30.5 kB
Release files / gw_sonification-0.1.0.tar.gz
| Download URL | gw_sonification-0.1.0.tar.gz |
|---|---|
| Size | 15.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9f68be7b1feeacf52a6da8c4674b881939cb6f0093fd5618bff2b2640cf265c7
|
|
BLAKE2b-256 checksum How to use checksums |
3894e6a2b01c2c227e3d4cd6996f6100d59c4fe45e560ce0a34f2b46f9090a92
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency logRelease files / gw_sonification-0.1.0-py3-none-any.whl
| Download URL | gw_sonification-0.1.0-py3-none-any.whl |
|---|---|
| Size | 14.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
06c1bbe617f6bd000a52f33ff977f524c89de7e08cb0c6a7fedcc463a89a653c
|
|
BLAKE2b-256 checksum How to use checksums |
c429e98b1bbac2e3e8243422149b57a5cf1819cd038761fd4940fcf4680d53b7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency logSecurity for gw-sonification 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for gw_sonification-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.