generator
birdnet_stm32.data.generator
¶
Batch generator and tf.data.Dataset wrapper for training and validation.
Uses multiprocessing.Pool for true parallel audio loading and
preprocessing, bypassing the GIL so FLAC decode, resampling, smart-crop,
and spectrogram computation run concurrently across CPU cores. A feeder
process runs the pool and assembles batches (birdnet_stm32.data.feeder).
Long files yield multiple salient chunks per open, stored in a shuffled in-memory reservoir to maximize I/O reuse and batch diversity.
mixup_batch(samples, labels, alpha=0.2, probability=0.25, cooccurrence=None)
¶
Multi-source mixup on a batch, in TensorFlow ops (runs inside tf.data, off the Python lock).
Emulates several birds calling at once: floor(B * probability) random samples of the batch
are each replaced by a blend of themselves and 1 or 2 random partners (even odds), with gains
from a Dirichlet(alpha) distribution (normalized Gamma draws), and their labels become the
element-wise max over the sources so every contributing species stays a target. Every blend
reads the original batch.
With cooccurrence (float [C, C], 1 where two classes can occur together, e.g. share a
geomodel region; non-bird classes with everything) the partners are drawn only among the batch
samples whose primary class (the label argmax) can co-occur with the sample's own; samples
without a positive label pair with anything. A sample always qualifies as its own partner, so
one with no plausible partner in the batch stays (nearly) unmixed.
Returns:
| Type | Description |
|---|---|
|
|
|
|
(the teacher embedding of such a chunk no longer describes its audio). |
Source code in birdnet_stm32/data/generator.py
estimate_samples_per_epoch(n_files, max_chunks_per_file=1)
¶
Estimate the number of samples produced per full pass over the files.
Short files produce 1 chunk, longer files up to max_chunks_per_file.
On average we estimate (1 + max_chunks_per_file) / 2 samples per file.
Source code in birdnet_stm32/data/generator.py
sample_chunks(file_paths, classes, audio_frontend='hybrid', spec_width=256, mel_bins=64, num_workers=8, max_chunks_per_file=1, **kwargs)
¶
Process each file once, exactly as a training loader would, and return the chunks.
A finite draw with the loader's own worker processing (crop policy, teacher
targets and embeddings) but no tf.data, reservoir or mixup: for
one-off statistics such as fitting a training-only head before training.
A second tf.data iterator over the infinite training loader would have to
be torn down mid-stream, and tearing down its worker pool can hang.
Returns:
| Type | Description |
|---|---|
list[tuple[ndarray, ...]]
|
The worker's tuples, in file order; files that fail to load are skipped. |
Source code in birdnet_stm32/data/generator.py
load_dataset(file_paths, classes, audio_frontend='hybrid', batch_size=32, spec_width=256, mel_bins=64, num_workers=8, max_chunks_per_file=1, **kwargs)
¶
Build a high-throughput tf.data pipeline with multiprocessing workers.
Uses multiprocessing.Pool so FLAC decode, resampling, smart-crop,
and spectrogram computation run in separate processes, bypassing the
GIL entirely.
When max_chunks_per_file > 1, each file open extracts up to that many
salient chunks, which are buffered in a shuffled in-memory reservoir.
This dramatically reduces redundant I/O for long recordings (e.g. a 60 s
file decoded once yields 3 usable chunks instead of 1).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_paths
|
list[str]
|
Audio file paths. |
required |
classes
|
list[str]
|
Ordered class names. |
required |
audio_frontend
|
str
|
'librosa' | 'hybrid' | 'raw'. |
'hybrid'
|
batch_size
|
int
|
Batch size. |
32
|
spec_width
|
int
|
Target spectrogram width. |
256
|
mel_bins
|
int
|
Number of mel bins. |
64
|
num_workers
|
int
|
Number of worker processes (0 = single-process fallback). |
8
|
max_chunks_per_file
|
int
|
Max salient chunks to extract per file open. |
1
|
**kwargs
|
Any
|
Forwarded to loading logic (sample_rate, chunk_duration, etc.). |
{}
|
Returns:
| Type | Description |
|---|---|
Dataset
|
Infinite tf.data.Dataset of (inputs, labels) with prefetching. With |
Dataset
|
|
Dataset
|
|
Dataset
|
float32 |
Dataset
|
chunks with no usable teacher window and for chunks mixup mixed, whose |
Dataset
|
audio the cached embedding no longer describes. With |
Dataset
|
folder built by |
Dataset
|
|
Dataset
|
valid, aux, aux_valid) |
Dataset
|
|
Source code in birdnet_stm32/data/generator.py
249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 | |