Skip to main content

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):

  1. Download 36 s of open strain data from GWOSC (cached locally).
  2. Detrend and apply a Tukey taper.
  3. Whiten using a 4 s FFT window with 2 s overlap.
  4. Bandpass filter: 30–400 Hz.
  5. Crop to a 32 s window centred 2 s after merger.
  6. Normalise to float32 in [−1, 1] and write as 16-bit PCM WAV.
  7. Apply each requested audio effect and write additional files.

For waveform templates (Waveform):

  1. Generate a time-domain IMRPhenomXPHM waveform via PyCBC.
  2. Extract a 4 s window around the merger.
  3. 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)

Source distribution for gw-sonification 0.1.0
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)

Table of built distributions (wheels) for gw-sonification 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page