zeechimp commited on
Commit
6f27a52
·
verified ·
1 Parent(s): a8c86d4

Upload hv_note.py

Browse files
Files changed (1) hide show
  1. hv_note.py +824 -0
hv_note.py ADDED
@@ -0,0 +1,824 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ hv-note
3
+ =======
4
+
5
+ Symbolic audio event extraction. No lexicon. No translation layer.
6
+
7
+ Given a WAV file, output a score: a sequence of (onset_frame, symbol_id)
8
+ pairs, where each symbol describes a discrete audio event by
9
+ (pitch_band, duration_class, amplitude_class).
10
+
11
+ The symbol alphabet is fixed and unnamed. Two recordings containing the
12
+ same pattern produce the same score. You do not need to know what the
13
+ pattern means to match it.
14
+
15
+ Pure stdlib. No dependencies.
16
+
17
+ Author: zeechimp
18
+ License: Apache-2.0
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import argparse
24
+ import json
25
+ import math
26
+ import os
27
+ import sys
28
+ import wave
29
+ from array import array
30
+ from collections import Counter
31
+ from dataclasses import asdict, dataclass, fields
32
+ from pathlib import Path
33
+ from typing import Dict, List, Optional, Tuple
34
+
35
+
36
+ # ============================================================================
37
+ # Pitch band grid (log-spaced, Hz)
38
+ # ============================================================================
39
+ def _log_bands(lo: float, hi: float, n: int) -> List[float]:
40
+ ratio = (hi / lo) ** (1.0 / (n - 1))
41
+ return [lo * (ratio ** i) for i in range(n)]
42
+
43
+
44
+ PITCH_BANDS: List[float] = _log_bands(80.0, 6000.0, 16)
45
+ N_BANDS: int = len(PITCH_BANDS)
46
+ N_DUR: int = 4
47
+ N_AMP: int = 3
48
+ N_SYMBOLS: int = N_BANDS * N_DUR * N_AMP # 192
49
+
50
+
51
+ def encode_symbol(band: int, dur: int, amp: int) -> int:
52
+ return band * (N_DUR * N_AMP) + dur * N_AMP + amp
53
+
54
+
55
+ def decode_symbol(sid: int) -> Tuple[int, int, int]:
56
+ band = sid // (N_DUR * N_AMP)
57
+ rem = sid % (N_DUR * N_AMP)
58
+ return band, rem // N_AMP, rem % N_AMP
59
+
60
+
61
+ # ============================================================================
62
+ # Config
63
+ # ============================================================================
64
+ @dataclass
65
+ class HVNoteConfig:
66
+ # Framing
67
+ frame_ms: float = 20.0
68
+ hop_ms: float = 10.0
69
+
70
+ # Onset detection
71
+ onset_floor: float = 0.02
72
+ onset_rise_mult: float = 1.5
73
+
74
+ # Event segmentation
75
+ min_peak_rms: float = 0.02
76
+ max_event_frames: int = 200
77
+ min_event_frames: int = 1
78
+
79
+ # Pitch window
80
+ pitch_window_s: float = 0.030
81
+
82
+ # Quantization
83
+ dur_bounds: Tuple[int, int, int] = (3, 8, 20)
84
+ amp_bounds: Tuple[float, float] = (0.3, 0.7)
85
+
86
+ # Corpus
87
+ max_files: int = 0
88
+ glob: str = "*.wav"
89
+
90
+ version: str = "0.1.4"
91
+
92
+
93
+ # ============================================================================
94
+ # Report dataclasses
95
+ # ============================================================================
96
+ @dataclass
97
+ class AudioEvent:
98
+ start_frame: int
99
+ end_frame: int
100
+ peak_frame: int
101
+ start_s: float
102
+ end_s: float
103
+ peak_s: float
104
+ peak_rms: float
105
+ pitch_hz: float
106
+ band: int
107
+ dur_class: int
108
+ amp_class: int
109
+ symbol: int
110
+
111
+ def to_dict(self) -> dict:
112
+ return {
113
+ "start_frame": self.start_frame,
114
+ "end_frame": self.end_frame,
115
+ "peak_frame": self.peak_frame,
116
+ "start_s": round(self.start_s, 4),
117
+ "end_s": round(self.end_s, 4),
118
+ "peak_s": round(self.peak_s, 4),
119
+ "peak_rms": round(self.peak_rms, 6),
120
+ "pitch_hz": round(self.pitch_hz, 2),
121
+ "band": self.band,
122
+ "dur_class": self.dur_class,
123
+ "amp_class": self.amp_class,
124
+ "symbol": self.symbol,
125
+ }
126
+
127
+
128
+ @dataclass
129
+ class ScoreReport:
130
+ path: str
131
+ sample_rate: int
132
+ duration_s: float
133
+ n_frames: int
134
+ n_samples: int
135
+ events: List[AudioEvent]
136
+ score: List[Tuple[int, int]]
137
+ histogram: Dict[int, int]
138
+ entropy_bits: float
139
+
140
+ def to_dict(self) -> dict:
141
+ return {
142
+ "path": self.path,
143
+ "sample_rate": self.sample_rate,
144
+ "duration_s": round(self.duration_s, 4),
145
+ "n_frames": self.n_frames,
146
+ "n_samples": self.n_samples,
147
+ "n_events": len(self.events),
148
+ "score": [[int(t), int(s)] for t, s in self.score],
149
+ "histogram": {str(k): v for k, v in self.histogram.items()},
150
+ "entropy_bits": round(self.entropy_bits, 4),
151
+ "events": [e.to_dict() for e in self.events],
152
+ }
153
+
154
+
155
+ @dataclass
156
+ class CorpusReport:
157
+ root: str
158
+ n_files: int
159
+ n_events: int
160
+ unique_symbols: int
161
+ total_entropy_bits: float
162
+ symbol_counts: Dict[int, int]
163
+ group_counts: Dict[str, int]
164
+ group_unique: Dict[str, int]
165
+ file_scores: Dict[str, List[int]]
166
+
167
+ def to_dict(self) -> dict:
168
+ return {
169
+ "root": self.root,
170
+ "n_files": self.n_files,
171
+ "n_events": self.n_events,
172
+ "unique_symbols": self.unique_symbols,
173
+ "total_entropy_bits": round(self.total_entropy_bits, 4),
174
+ "symbol_counts": {str(k): v for k, v in self.symbol_counts.items()},
175
+ "group_counts": dict(self.group_counts),
176
+ "group_unique": dict(self.group_unique),
177
+ "file_scores": {k: list(v) for k, v in self.file_scores.items()},
178
+ }
179
+
180
+
181
+ # ============================================================================
182
+ # Audio I/O & primitives
183
+ # ============================================================================
184
+ def read_wav(path: str) -> Tuple[array, int]:
185
+ """Return (samples_int16, sample_rate). Left channel only."""
186
+ with wave.open(path, "rb") as w:
187
+ n_ch = w.getnchannels()
188
+ sw = w.getsampwidth()
189
+ sr = w.getframerate()
190
+ n = w.getnframes()
191
+ raw = w.readframes(n)
192
+
193
+ if sw != 2:
194
+ raise ValueError(f"Only 16-bit PCM WAV supported, got {sw*8}-bit")
195
+
196
+ samples = array("h")
197
+ samples.frombytes(raw)
198
+
199
+ if n_ch > 1:
200
+ samples = samples[::n_ch]
201
+
202
+ return samples, sr
203
+
204
+
205
+ def rms_norm(chunk: array) -> float:
206
+ n = len(chunk)
207
+ if n == 0:
208
+ return 0.0
209
+ s = 0
210
+ for x in chunk:
211
+ s += x * x
212
+ return math.sqrt(s / n) / 32768.0
213
+
214
+
215
+ def goertzel_power(window: array, target_hz: float, sr: int) -> float:
216
+ n = len(window)
217
+ if n == 0 or target_hz >= sr / 2:
218
+ return 0.0
219
+ k = int(0.5 + n * target_hz / sr)
220
+ if k < 1:
221
+ k = 1
222
+ omega = 2.0 * math.pi * k / n
223
+ coeff = 2.0 * math.cos(omega)
224
+ s_prev = 0.0
225
+ s_prev2 = 0.0
226
+ for x in window:
227
+ s = x + coeff * s_prev - s_prev2
228
+ s_prev2 = s_prev
229
+ s_prev = s
230
+ return s_prev2 * s_prev2 + s_prev * s_prev - coeff * s_prev * s_prev2
231
+
232
+
233
+ def entropy_bits(counts: Dict[int, int]) -> float:
234
+ total = sum(counts.values())
235
+ if total == 0:
236
+ return 0.0
237
+ e = 0.0
238
+ for c in counts.values():
239
+ if c > 0:
240
+ p = c / total
241
+ e -= p * math.log2(p)
242
+ return e
243
+
244
+
245
+ # ============================================================================
246
+ # The model
247
+ # ============================================================================
248
+ class HVNote:
249
+ """Symbolic audio event extraction."""
250
+
251
+ def __init__(self, config: Optional[HVNoteConfig] = None):
252
+ self.config = config or HVNoteConfig()
253
+ self._obs = 0
254
+
255
+ def __repr__(self) -> str:
256
+ return (
257
+ f"HVNote(frame_ms={self.config.frame_ms}, "
258
+ f"hop_ms={self.config.hop_ms}, "
259
+ f"n_symbols={N_SYMBOLS}, "
260
+ f"version={self.config.version})"
261
+ )
262
+
263
+ # ------------------------------------------------------------------
264
+ # Framing
265
+ # ------------------------------------------------------------------
266
+ def _frame_rms(self, samples: array, sr: int) -> Tuple[List[float], int, int]:
267
+ win = max(1, int(sr * self.config.frame_ms / 1000))
268
+ hop = max(1, int(sr * self.config.hop_ms / 1000))
269
+ rms_vals: List[float] = []
270
+ i = 0
271
+ n = len(samples)
272
+ while i + win <= n:
273
+ rms_vals.append(rms_norm(samples[i:i + win]))
274
+ i += hop
275
+ return rms_vals, win, hop
276
+
277
+ # ------------------------------------------------------------------
278
+ # Event detection
279
+ # ------------------------------------------------------------------
280
+ def _detect_events(
281
+ self, rms_vals: List[float]
282
+ ) -> List[Tuple[int, int, int, float]]:
283
+ """
284
+ Onset + extent in a single forward scan.
285
+
286
+ Onset fires at frame i when rms[i] >= onset_floor AND either:
287
+ - rms[i] >= rms[i-1] * onset_rise_mult (sharp rise), or
288
+ - rms[i-1] < onset_floor (silence crossing).
289
+
290
+ The event's extent is the connected region above onset_floor
291
+ starting at the onset. The peak is argmax over that region only —
292
+ never over a fixed search horizon. This prevents a later, louder
293
+ event from hijacking the current one.
294
+ """
295
+ n = len(rms_vals)
296
+ if n == 0:
297
+ return []
298
+
299
+ floor = self.config.onset_floor
300
+ rise_mult = self.config.onset_rise_mult
301
+
302
+ events: List[Tuple[int, int, int, float]] = []
303
+ i = 0
304
+ while i < n:
305
+ cur = rms_vals[i]
306
+ if cur < floor:
307
+ i += 1
308
+ continue
309
+
310
+ prev = rms_vals[i - 1] if i > 0 else 0.0
311
+ is_rise = (i == 0) or (prev > 1e-9 and cur >= prev * rise_mult)
312
+ is_crossing = prev < floor
313
+ if not (is_rise or is_crossing):
314
+ i += 1
315
+ continue
316
+
317
+ # Extent: stay in the connected region above floor.
318
+ max_end = min(n, i + self.config.max_event_frames)
319
+ end = i
320
+ while end < max_end and rms_vals[end] >= floor:
321
+ end += 1
322
+
323
+ if end - i < self.config.min_event_frames:
324
+ i += 1
325
+ continue
326
+
327
+ # Peak is argmax over the extent only.
328
+ peak_frame = max(range(i, end), key=lambda j: rms_vals[j])
329
+ peak_rms = rms_vals[peak_frame]
330
+ if peak_rms < self.config.min_peak_rms:
331
+ i += 1
332
+ continue
333
+
334
+ events.append((i, end, peak_frame, peak_rms))
335
+ # Skip past the whole event.
336
+ i = max(i + 1, end)
337
+
338
+ return events
339
+
340
+ # ------------------------------------------------------------------
341
+ # Pitch band
342
+ # ------------------------------------------------------------------
343
+ def _pitch_band(
344
+ self, samples: array, sr: int, peak_frame: int, hop: int
345
+ ) -> Tuple[int, float]:
346
+ window_len = max(1, int(sr * self.config.pitch_window_s))
347
+ center = peak_frame * hop + (hop // 2)
348
+ start = max(0, center - window_len // 2)
349
+ end = min(len(samples), start + window_len)
350
+ window = samples[start:end]
351
+ if len(window) < 8:
352
+ return 0, 0.0
353
+
354
+ best_band = 0
355
+ best_power = -1.0
356
+ for bi, f in enumerate(PITCH_BANDS):
357
+ p = goertzel_power(window, f, sr)
358
+ if p > best_power:
359
+ best_power = p
360
+ best_band = bi
361
+ return best_band, PITCH_BANDS[best_band]
362
+
363
+ # ------------------------------------------------------------------
364
+ # Quantization
365
+ # ------------------------------------------------------------------
366
+ def _dur_class(self, length: int) -> int:
367
+ b0, b1, b2 = self.config.dur_bounds
368
+ if length < b0:
369
+ return 0
370
+ if length < b1:
371
+ return 1
372
+ if length < b2:
373
+ return 2
374
+ return 3
375
+
376
+ def _amp_class(self, peak_rms: float, recording_peak: float) -> int:
377
+ if recording_peak <= 0:
378
+ return 0
379
+ r = peak_rms / recording_peak
380
+ a0, a1 = self.config.amp_bounds
381
+ if r < a0:
382
+ return 0
383
+ if r < a1:
384
+ return 1
385
+ return 2
386
+
387
+ # ------------------------------------------------------------------
388
+ # Public API
389
+ # ------------------------------------------------------------------
390
+ def score_file(self, path: str) -> ScoreReport:
391
+ samples, sr = read_wav(path)
392
+ return self.score_samples(samples, sr, path=path)
393
+
394
+ def score_samples(
395
+ self, samples: array, sr: int, path: str = "<memory>"
396
+ ) -> ScoreReport:
397
+ rms_vals, win, hop = self._frame_rms(samples, sr)
398
+ n_frames = len(rms_vals)
399
+ recording_peak = max(rms_vals) if rms_vals else 0.0
400
+
401
+ raw_events = self._detect_events(rms_vals)
402
+
403
+ events: List[AudioEvent] = []
404
+ for start, end, peak_frame, peak_rms in raw_events:
405
+ band, hz = self._pitch_band(samples, sr, peak_frame, hop)
406
+ dur = self._dur_class(end - start)
407
+ amp = self._amp_class(peak_rms, recording_peak)
408
+ sym = encode_symbol(band, dur, amp)
409
+ events.append(AudioEvent(
410
+ start_frame=start,
411
+ end_frame=end,
412
+ peak_frame=peak_frame,
413
+ start_s=start * self.config.hop_ms / 1000.0,
414
+ end_s=end * self.config.hop_ms / 1000.0,
415
+ peak_s=peak_frame * self.config.hop_ms / 1000.0,
416
+ peak_rms=peak_rms,
417
+ pitch_hz=hz,
418
+ band=band,
419
+ dur_class=dur,
420
+ amp_class=amp,
421
+ symbol=sym,
422
+ ))
423
+
424
+ score = [(e.start_frame, e.symbol) for e in events]
425
+ hist = Counter(e.symbol for e in events)
426
+ hist_dict = {int(k): int(v) for k, v in hist.items()}
427
+ ent = entropy_bits(hist_dict)
428
+ dur = len(samples) / sr if sr > 0 else 0.0
429
+
430
+ self._obs += 1
431
+ return ScoreReport(
432
+ path=path,
433
+ sample_rate=sr,
434
+ duration_s=dur,
435
+ n_frames=n_frames,
436
+ n_samples=len(samples),
437
+ events=events,
438
+ score=score,
439
+ histogram=hist_dict,
440
+ entropy_bits=ent,
441
+ )
442
+
443
+ def score_directory(
444
+ self, root: str, max_files: Optional[int] = None
445
+ ) -> CorpusReport:
446
+ root_path = Path(root)
447
+ if not root_path.exists():
448
+ raise FileNotFoundError(root)
449
+
450
+ files = sorted(root_path.rglob(self.config.glob))
451
+ if not files:
452
+ raise FileNotFoundError(
453
+ f"No files matching {self.config.glob!r} under {root}"
454
+ )
455
+
456
+ limit = max_files if max_files is not None else self.config.max_files
457
+ if limit and limit > 0:
458
+ files = files[:limit]
459
+
460
+ symbol_counts: Counter = Counter()
461
+ group_counts: Counter = Counter()
462
+ group_symbols: Dict[str, set] = {}
463
+ file_scores: Dict[str, List[int]] = {}
464
+ total_events = 0
465
+
466
+ for f in files:
467
+ try:
468
+ report = self.score_file(str(f))
469
+ except Exception as e:
470
+ print(f" skip {f.name}: {e}", file=sys.stderr)
471
+ continue
472
+
473
+ file_scores[str(f)] = [s for _, s in report.score]
474
+ total_events += len(report.score)
475
+
476
+ group_key = self._group_key(f.stem)
477
+ group_counts[group_key] += 1
478
+ group_symbols.setdefault(group_key, set())
479
+ group_symbols[group_key].update(s for _, s in report.score)
480
+ symbol_counts.update(s for _, s in report.score)
481
+
482
+ symbol_counts_dict = {int(k): int(v) for k, v in symbol_counts.items()}
483
+ group_unique = {k: len(v) for k, v in group_symbols.items()}
484
+ ent = entropy_bits(symbol_counts_dict)
485
+
486
+ return CorpusReport(
487
+ root=str(root),
488
+ n_files=len(file_scores),
489
+ n_events=total_events,
490
+ unique_symbols=len(symbol_counts),
491
+ total_entropy_bits=ent,
492
+ symbol_counts=symbol_counts_dict,
493
+ group_counts={k: int(v) for k, v in group_counts.items()},
494
+ group_unique=group_unique,
495
+ file_scores=file_scores,
496
+ )
497
+
498
+ @staticmethod
499
+ def _group_key(stem: str) -> str:
500
+ for sep in ("_", "-"):
501
+ if sep in stem:
502
+ return stem.split(sep)[0]
503
+ return stem
504
+
505
+ # ------------------------------------------------------------------
506
+ # Convenience
507
+ # ------------------------------------------------------------------
508
+ def score(self, path: str) -> List[int]:
509
+ return [s for _, s in self.score_file(path).score]
510
+
511
+ def fingerprint(self, path: str, k: int = 8) -> Tuple[int, ...]:
512
+ s = self.score(path)
513
+ return tuple(s[:k])
514
+
515
+ # ------------------------------------------------------------------
516
+ # Rendering
517
+ # ------------------------------------------------------------------
518
+ def render_file(self, report: ScoreReport) -> str:
519
+ lines: List[str] = []
520
+ bar = "=" * 72
521
+ lines.append(bar)
522
+ lines.append("hv-note — symbolic audio score")
523
+ lines.append(bar)
524
+ lines.append("")
525
+ lines.append(f" file : {report.path}")
526
+ lines.append(f" duration : {report.duration_s:.3f} s")
527
+ lines.append(f" sample rate: {report.sample_rate} Hz")
528
+ lines.append(f" frames : {report.n_frames}")
529
+ lines.append(f" events : {len(report.events)}")
530
+ lines.append(f" unique sym : {len(report.histogram)}")
531
+ lines.append(f" entropy : {report.entropy_bits:.3f} bits")
532
+ lines.append("")
533
+
534
+ if not report.events:
535
+ lines.append(" (no events detected)")
536
+ return "\n".join(lines)
537
+
538
+ lines.append(" SCORE")
539
+ lines.append(" " + "-" * 68)
540
+ lines.append(
541
+ f" {'frame':>6} {'time':>7} {'sym':>4} "
542
+ f"(band, dur, amp) {'pitch':>8} rms"
543
+ )
544
+ for e in report.events:
545
+ lines.append(
546
+ f" {e.start_frame:>6} {e.start_s:>6.3f}s "
547
+ f"{e.symbol:>4} "
548
+ f"({e.band:>2}, {e.dur_class}, {e.amp_class}) "
549
+ f"{e.pitch_hz:>7.1f}Hz {e.peak_rms:.4f}"
550
+ )
551
+ lines.append("")
552
+
553
+ lines.append(" HISTOGRAM")
554
+ lines.append(" " + "-" * 68)
555
+ for sym, count in sorted(
556
+ report.histogram.items(), key=lambda kv: -kv[1]
557
+ ):
558
+ band, dur, amp = decode_symbol(sym)
559
+ lines.append(
560
+ f" {sym:>4} ({band:>2}, {dur}, {amp}) {count:>4}"
561
+ )
562
+ lines.append("")
563
+
564
+ if len(report.score) >= 2:
565
+ lines.append(" TRANSITIONS (top 8)")
566
+ lines.append(" " + "-" * 68)
567
+ trans: Counter = Counter()
568
+ for i in range(len(report.score) - 1):
569
+ a = report.score[i][1]
570
+ b = report.score[i + 1][1]
571
+ trans[(a, b)] += 1
572
+ for (a, b), c in trans.most_common(8):
573
+ lines.append(f" {a:>4} -> {b:<4} {c:>4}")
574
+ lines.append("")
575
+
576
+ return "\n".join(lines)
577
+
578
+ def render_corpus(self, report: CorpusReport) -> str:
579
+ lines: List[str] = []
580
+ bar = "=" * 72
581
+ lines.append(bar)
582
+ lines.append("hv-note — corpus of symbolic audio scores")
583
+ lines.append(bar)
584
+ lines.append("")
585
+ lines.append(f" root : {report.root}")
586
+ lines.append(f" files : {report.n_files}")
587
+ lines.append(f" events : {report.n_events}")
588
+ lines.append(f" unique sym : {report.unique_symbols} / {N_SYMBOLS}")
589
+ lines.append(f" entropy : {report.total_entropy_bits:.3f} bits")
590
+ lines.append("")
591
+
592
+ if report.symbol_counts:
593
+ lines.append(" TOP SYMBOLS")
594
+ lines.append(" " + "-" * 68)
595
+ lines.append(
596
+ f" {'sym':>4} (band, dur, amp) count"
597
+ )
598
+ for sym, count in sorted(
599
+ report.symbol_counts.items(), key=lambda kv: -kv[1]
600
+ )[:15]:
601
+ band, dur, amp = decode_symbol(sym)
602
+ lines.append(
603
+ f" {sym:>4} ({band:>2}, {dur}, {amp}) "
604
+ f"{count:>6}"
605
+ )
606
+ lines.append("")
607
+
608
+ if report.group_counts:
609
+ lines.append(" PER-GROUP SUMMARY")
610
+ lines.append(" " + "-" * 68)
611
+ lines.append(
612
+ f" {'group':<20} {'files':>6} {'unique_sym':>10}"
613
+ )
614
+ for g, count in sorted(
615
+ report.group_counts.items(), key=lambda kv: -kv[1]
616
+ )[:20]:
617
+ uniq = report.group_unique.get(g, 0)
618
+ lines.append(f" {g:<20} {count:>6} {uniq:>10}")
619
+ lines.append("")
620
+
621
+ return "\n".join(lines)
622
+
623
+ # ------------------------------------------------------------------
624
+ # Persistence
625
+ # ------------------------------------------------------------------
626
+ def save_pretrained(self, save_dir: str) -> None:
627
+ os.makedirs(save_dir, exist_ok=True)
628
+ payload = {
629
+ "config": asdict(self.config),
630
+ "observations": self._obs,
631
+ "pitch_bands": list(PITCH_BANDS),
632
+ "n_symbols": N_SYMBOLS,
633
+ }
634
+ with open(os.path.join(save_dir, "config.json"), "w") as f:
635
+ json.dump(payload, f, indent=2)
636
+
637
+ @classmethod
638
+ def from_pretrained(cls, save_dir: str) -> "HVNote":
639
+ with open(os.path.join(save_dir, "config.json"), "r") as f:
640
+ payload = json.load(f)
641
+ cfg_dict = payload.get("config", {})
642
+ known = {f.name for f in fields(HVNoteConfig)}
643
+ cfg_dict = {k: v for k, v in cfg_dict.items() if k in known}
644
+ cfg = HVNoteConfig(**cfg_dict)
645
+ obj = cls(config=cfg)
646
+ obj._obs = int(payload.get("observations", 0))
647
+ return obj
648
+
649
+
650
+ # ============================================================================
651
+ # Demo
652
+ # ============================================================================
653
+ def _write_wav(path: str, samples: List[float], sr: int) -> None:
654
+ ints = array(
655
+ "h",
656
+ (max(-32768, min(32767, int(x * 32767))) for x in samples),
657
+ )
658
+ with wave.open(path, "wb") as w:
659
+ w.setnchannels(1)
660
+ w.setsampwidth(2)
661
+ w.setframerate(sr)
662
+ w.writeframes(ints.tobytes())
663
+
664
+
665
+ def _synth_beeps(freqs: List[float], dur_ms: int, gap_ms: int,
666
+ sr: int = 16000) -> List[float]:
667
+ out: List[float] = []
668
+ for f in freqs:
669
+ n = int(sr * dur_ms / 1000)
670
+ for i in range(n):
671
+ t = i / sr
672
+ env = math.sin(math.pi * i / n) ** 0.5
673
+ out.append(0.5 * env * math.sin(2 * math.pi * f * t))
674
+ out.extend([0.0] * int(sr * gap_ms / 1000))
675
+ return out
676
+
677
+
678
+ def _synth_chirp(f0: float, f1: float, dur_ms: int,
679
+ sr: int = 16000) -> List[float]:
680
+ n = int(sr * dur_ms / 1000)
681
+ dur_s = dur_ms / 1000.0
682
+ out: List[float] = []
683
+ for i in range(n):
684
+ t = i / sr
685
+ phase = 2 * math.pi * (f0 * t + 0.5 * (f1 - f0) * t * t / dur_s)
686
+ env = math.sin(math.pi * i / n)
687
+ out.append(0.5 * env * math.sin(phase))
688
+ return out
689
+
690
+
691
+ def _synth_claps(dur_ms: int, gap_ms: int, seed: int = 42,
692
+ sr: int = 16000) -> List[float]:
693
+ import random
694
+ rng = random.Random(seed)
695
+ out: List[float] = []
696
+ for _ in range(4):
697
+ n = int(sr * dur_ms / 1000)
698
+ for i in range(n):
699
+ env = math.exp(-i / (n * 0.3))
700
+ out.append(0.7 * env * (rng.random() * 2 - 1))
701
+ out.extend([0.0] * int(sr * gap_ms / 1000))
702
+ return out
703
+
704
+
705
+ def _demo(output_dir: str = "./hv_note_output") -> None:
706
+ os.makedirs(output_dir, exist_ok=True)
707
+ m = HVNote()
708
+
709
+ samples: List[Tuple[str, List[float], int]] = [
710
+ ("beeps_low", _synth_beeps([220, 220, 220], 150, 100), 16000),
711
+ ("beeps_high", _synth_beeps([880, 660, 440], 120, 90), 16000),
712
+ ("chirp_up", _synth_chirp(200, 2000, 800), 16000),
713
+ ("claps", _synth_claps(60, 180), 16000),
714
+ ]
715
+
716
+ print()
717
+ print("=" * 72)
718
+ print("hv-note — demo on synthesized audio")
719
+ print("=" * 72)
720
+ print()
721
+
722
+ paths: List[str] = []
723
+ for name, sig, sr in samples:
724
+ path = os.path.join(output_dir, f"{name}.wav")
725
+ _write_wav(path, sig, sr)
726
+ paths.append(path)
727
+ print(f" wrote {path} ({len(sig)} samples @ {sr} Hz)")
728
+
729
+ print()
730
+ for path in paths:
731
+ report = m.score_file(path)
732
+ print(m.render_file(report))
733
+ print()
734
+
735
+ print("=" * 72)
736
+ print("Summary")
737
+ print("=" * 72)
738
+ print(f" {'file':<24} {'events':>6} {'unique':>6} {'entropy':>8}")
739
+ print(" " + "-" * 60)
740
+ for path in paths:
741
+ r = m.score_file(path)
742
+ print(
743
+ f" {Path(path).name:<24} {len(r.events):>6} "
744
+ f"{len(r.histogram):>6} {r.entropy_bits:>7.3f}b"
745
+ )
746
+
747
+ print()
748
+ print("=" * 72)
749
+ print("Corpus mode (over the demo folder)")
750
+ print("=" * 72)
751
+ corpus = m.score_directory(output_dir)
752
+ print(m.render_corpus(corpus))
753
+
754
+ print("=" * 72)
755
+ print("Save / load round trip")
756
+ print("=" * 72)
757
+ save_path = os.path.join(output_dir, "hv_note_model")
758
+ m.save_pretrained(save_path)
759
+ m2 = HVNote.from_pretrained(save_path)
760
+ print(f" saved to : {save_path}")
761
+ print(f" reloaded : {m2!r}")
762
+ a = m.score(paths[0])
763
+ b = m2.score(paths[0])
764
+ print(f" score [0] : {a}")
765
+ print(f" reloaded : {b}")
766
+ print(f" identical : {a == b}")
767
+ print()
768
+
769
+
770
+ # ============================================================================
771
+ # CLI
772
+ # ============================================================================
773
+ def _cli() -> None:
774
+ p = argparse.ArgumentParser(
775
+ description="hv-note: symbolic audio event extraction."
776
+ )
777
+ p.add_argument("--file", type=str, default="",
778
+ help="score a single WAV file")
779
+ p.add_argument("--dir", type=str, default="",
780
+ help="score every WAV under a directory")
781
+ p.add_argument("--limit", type=int, default=0,
782
+ help="max files in --dir mode (0 = all)")
783
+ p.add_argument("--json", action="store_true",
784
+ help="output JSON instead of a rendered report")
785
+ p.add_argument("--fingerprint", action="store_true",
786
+ help="print only the fingerprint of a single file")
787
+ p.add_argument("--save-to", type=str, default="",
788
+ help="save the model to this directory")
789
+ p.add_argument("--outdir", type=str, default="./hv_note_output")
790
+ args = p.parse_args()
791
+
792
+ m = HVNote()
793
+ if args.save_to:
794
+ m.save_pretrained(args.save_to)
795
+ print(f"saved to {args.save_to}", file=sys.stderr)
796
+
797
+ if args.fingerprint:
798
+ if not args.file:
799
+ p.error("--fingerprint requires --file")
800
+ fp = m.fingerprint(args.file)
801
+ print(json.dumps(list(fp)))
802
+ return
803
+
804
+ if args.file:
805
+ report = m.score_file(args.file)
806
+ if args.json:
807
+ print(json.dumps(report.to_dict(), indent=2))
808
+ else:
809
+ print(m.render_file(report))
810
+ return
811
+
812
+ if args.dir:
813
+ corpus = m.score_directory(args.dir, max_files=args.limit or None)
814
+ if args.json:
815
+ print(json.dumps(corpus.to_dict(), indent=2))
816
+ else:
817
+ print(m.render_corpus(corpus))
818
+ return
819
+
820
+ _demo(args.outdir)
821
+
822
+
823
+ if __name__ == "__main__":
824
+ _cli()