Skip to content

api-reference.md

Latest commit

 

History

History
71 lines (48 loc) · 2.28 KB

api-reference.md

File metadata and controls

71 lines (48 loc) · 2.28 KB
Raw

API reference

The public surface of sonoscript. Import everything from the top-level package:

import sonoscript as ss

Audio containers

AudioClip(samples, sample_rate)

An immutable mono float32 clip. samples is coerced to a contiguous 1-D float32 array.

Member Description
num_samples, duration_seconds, is_empty Basic properties.
AudioClip.silence(duration, sample_rate) Construct a silent clip.
slice_seconds(start, end) Extract a time window (bounds are clamped).
concat(other) / a + b Join two clips of the same sample rate.
apply_gain_db(db) Scale amplitude in decibels.
fade_in(seconds) / fade_out(seconds) Linear fades.
seconds_to_samples(s) / samples_to_seconds(n) Time/index conversion.

SoundEvent(label, onset, offset, score=1.0)

A labelled [onset, offset) region in seconds, with duration, midpoint, overlaps(other) and shifted(delta).

Editing

apply_script(clip, script) -> AudioClip

Parse script and apply every instruction to clip. The one-call entry point.

Editor(clip)

Builds up edits and renders them in one pass.

Method Description
insert_event(event, at) Splice a waveform in at a time.
delete_region(start, end) Remove a window.
replace_region(start, end, event) Swap a window for a waveform.
apply(command) / apply_all(commands) Queue parsed DSL commands.
render() -> AudioClip Compile the queued edits; fills .manifest.

Editor.crossfade_seconds (default 0.01) controls the seam crossfade width.

I/O

  • load_wav(path, allow_downmix=False) -> AudioClip
  • write_wav(path, clip) -> None

Both work with mono 16-bit PCM WAV. A multi-channel file raises unless allow_downmix=True.

Detection

detect_events(clip, threshold=None, ..., min_duration=0.05, merge_gap=0.03) returns a list of SoundEvents from the clip's short-time RMS energy.

Evaluation

  • evaluate_edit(clip, script) -> EditReport — apply and summarise in one call.
  • EditReport.to_dict() — a JSON-friendly summary (edits, durations, preserved SNR, seam smoothness).

Lower-level metrics live in sonoscript.evaluate: segmental_snr, preserved_snr, seam_discontinuity and event_prf.