55 lines (42 loc) · 2.1 KB

API 参考

仅列出稳定的公共接口。完整签名以源码 docstring 为准。

顶层 `sonoscribe`

名称	说明
`FeatureConfig`	统一的特征参数数据类
`read_wav(path, *, mono=True)`	读取 WAV，返回 `(samples, sr)`
`write_wav(path, samples, sr)`	写出 16-bit PCM WAV
`log_mel_spectrogram(x, cfg)`	对数梅尔谱 `(n_frames, n_mels)`
`mfcc(x, cfg)`	MFCC 系数 `(n_frames, n_mfcc)`
`PredictiveEncoder`	纯 NumPy 自监督编码器
`HandcraftedEncoder`	统计池化基线编码器
`Embedding`	表示结果（`vector` / `frames`）
`SceneTagger`	启发式场景标注器
`build_report(x, cfg=None)`	构造 `AcousticReport`
`describe_audio(x, *, lang="zh", client=None)`	一步生成场景描述

`sonoscribe.features`

stft(x, n_fft, hop_length, *, window="hann", center=False)
power_spectrogram(x, n_fft, hop_length, *, power=2.0)
mel_filterbank(sr, n_fft, n_mels, fmin=0, fmax=None)
delta(feat, width=9)
spectral_centroid / spectral_bandwidth / spectral_rolloff / spectral_flatness
zero_crossing_rate(x, frame_length, hop_length) / rms_energy(...)

`sonoscribe.represent`

PredictiveEncoder(config, *, hidden_dim, context, horizon, seed, pool_stats)
- .fit(signals, *, epochs, batch_size, lr) → self
- .embed(x) → Embedding
- .save(path) / PredictiveEncoder.load(path)
RandomProjection / PCAWhitening：降维工具
pool_frames(frames, stats=("mean", "std"))

`sonoscribe.scene`

AcousticReport：.to_dict() / .to_json()
SceneTagger：.tag(x, top_k=3) / .confidences(x) / .raw_scores(x)
TAXONOMY：内置场景标签集合

`sonoscribe.describe`

Describer(config, *, lang, client) → .describe(x) → Description
LLMClient 协议：describe(report, *, lang) -> str
客户端：OfflineTemplateClient / EchoClient / OpenAICompatClient

异常

所有异常继承自 sonoscribe.exceptions.SonoScribeError： AudioIOError、FeatureError、RepresentationError、DescribeError、 BackendNotAvailable。