buddybird-ai/parrot-sound-gate

BuddyBird Parrot Sound Classifier v2.0.0

English

Model description

This binary audio classifier labels an audio clip as parrot or non-parrot based on whether it contains a parrot sound. It combines a frozen Perch 2.0 ONNX encoder with a standardized L2 logistic-regression probe (C=0.0003) trained with balanced class weights and inverse source-group weights.

Intended use

• Classify WAV audio as parrot or non-parrot.
• Unlike v1, v2 targets small and medium parrot species only. Large parrots are out of scope (see Limitations).
• It assumes an upstream step-1 loudness gate has already dropped very quiet clips (max 100 ms-window RMS below −39 dBFS). It always returns one clip-level decision, even for a silent clip, but its decisions are unreliable on very quiet clips.

Installation

This model uses Python 3.12 and uv. It was tested on macOS 26.5.1 running on Apple Silicon. Exact dependency versions are recorded in uv.lock.

uv sync --frozen

The first prediction downloads the pinned Perch 2.0 ONNX file (about 390 MB) from justinchuby/Perch-onnx. Both the probe and Perch artifacts are checked against the SHA-256 values in model_manifest.json before they are loaded.

Quick start

from inference import ParrotSoundGate

gate = ParrotSoundGate.from_pretrained(
    "buddybird-ai/parrot-sound-gate",
    revision="v2.0.0",
)
result = gate.predict_file("clip.wav")
print(result)
# {"probability": 0.9312..., "is_parrot": True}

Command-line use:

uv run --frozen python inference.py clip.wav --revision v2.0.0

Input and output contract

The model accepts either a file path or a NumPy waveform with its sample rate. Multi-channel input is averaged to mono and resampled to 32 kHz. Unlike v1, v2 does not rescale the audio's volume to a fixed peak level; the original loudness is kept as is. The waveform is split into 5.0-second windows with a 2.5-second hop, encoded to 1,536 dimensions, and mean-pooled across windows. Short clips are zero-padded.

• probability: the logistic-regression positive-class score. It is not a calibrated confidence score.
• is_parrot: True for parrot and False for non-parrot, determined by probability >= 0.7122538089752197.

Training data summary

The model was trained on 18,175 clips, 6,580 of which were positive (parrot) examples and 11,595 negative (non-parrot) examples.

Evaluation

The reported numbers come from development evaluation with repeated nested cross-validation (outer 5-fold, inner 4-fold, averaged over seeds 0, 1, 2).

The operating threshold was selected from grouped out-of-fold scores using bucket false-accept-rate (FAR) caps at 50%, targeting a service-guardian FAR of 1%, an ambient human-voice FAR of 1%, and a noise FAR of 1.5%.

Metric	Development mean
Parrot recall	91.3%
Human-voice FAR	1.0%
Noise FAR	1.4%

Limitations

• The model returns one clip-level decision. It does not localize sound events, identify species, identify individuals, or judge successful word mimicry.
• v2 targets small and medium parrots; large parrots are out of scope and their recall is low (4/85 per seed).

Credit

This work was supported by the Institute of Information & Communications Technology Planning & Evaluation (IITP) grant funded by the Ministry of Science and ICT (MSIT) (IITP-2026-AI·SW Maestro)

한국어

모델 설명

이 모델은 audio clip에 앵무새 소리가 포함됐는지 판정해 parrot 또는 non-parrot으로 분류하는 binary audio classifier다. 고정된 Perch 2.0 ONNX encoder와 표준화된 L2 logistic-regression probe(C=0.0003)를 결합했고, balanced 클래스 가중치와 출처 그룹 역수 가중치로 학습했다.

사용 목적

• WAV audio를 parrot 또는 non-parrot으로 분류
• v1과 달리 v2는 소형·중형 앵무만 대상으로 한다. 대형 앵무는 대상 범위 밖이다(한계 참고).
• 너무 조용한 클립(최대 100ms 창 RMS가 −39 dBFS 미만)이 이미 걸러진 것을 가정한다. 무음 clip이 들어와도 항상 clip 단위 판정 하나를 반환하지만, 매우 조용한 클립에서는 판정이 불안정하다.

설치

Python 3.12와 uv를 사용한다. Apple Silicon 기반 macOS 26.5.1에서 검증되었다. 정확한 의존성 버전은 uv.lock에 기록되어 있다.

uv sync --frozen

최초 추론 때 justinchuby/Perch-onnx에서 고정된 Perch 2.0 ONNX file 약 390 MB를 내려받는다. loader는 probe와 Perch artifact를 load하기 전에 model_manifest.json에 고정된 SHA-256과 비교한다.

빠른 시작

from inference import ParrotSoundGate

gate = ParrotSoundGate.from_pretrained(
    "buddybird-ai/parrot-sound-gate",
    revision="v2.0.0",
)
result = gate.predict_file("clip.wav")
print(result)
# {"probability": 0.9312..., "is_parrot": True}

command line에서는 다음처럼 실행한다.

uv run --frozen python inference.py clip.wav --revision v2.0.0

입력과 출력 계약

file path 또는 sample rate와 NumPy waveform을 받는다. multi-channel 입력은 mono 평균, 32 kHz resample 순으로 처리한다.

v1과 달리 v2는 입력 음량을 일정한 최댓값으로 맞추는 정규화를 하지 않고 원본 음량을 그대로 사용한다. 이후 5.0초 window와 2.5초 hop 분할, 1,536차원 embedding, window 평균 pooling 순으로 처리한다. 짧은 clip은 0으로 padding한다.

• probability: logistic-regression의 positive-class score이며 보정된 confidence가 아니다.
• is_parrot: probability >= 0.7122538089752197이면 parrot을 뜻하는 True, 아니면 non-parrot을 뜻하는 False다.

학습 데이터 요약

모델은 18,175개 clip으로 학습했으며, 이 중 6,580개가 앵무새 positive clip, 11,595개가 비앵무새 negative clip이다.

평가

아래 수치는 repeated nested 교차검증(outer 5-fold, inner 4-fold, seed 0·1·2 평균)의 개발 평가 결과다.

운영 threshold는 그룹 out-of-fold 점수에서 bucket FAR 상한 50%로 선택했으며, 서비스 보호자 FAR 1%, ambient 사람 음성 FAR 1%, 잡음 FAR 1.5%를 목표로 했다.

지표	개발 평균
앵무새 recall	91.3%
사람 음성 FAR	1.0%
잡음 FAR	1.4%

한계

• clip 단위 판정만 제공한다. sound event 위치, 종, 개체, 단어 모사 성공 여부는 판정하지 않는다.
• v2는 소형·중형 앵무 대상이며 대형 앵무는 대상 범위 밖이고 recall이 낮다(각 seed 4/85).

Credit

이 성과는 2026년도 과학기술정보통신부의 재원으로 정보통신기획평가원의 지원을 받아 수행된 결과물임 (IITP-2026-AI·SW마에스트로)