tphakala/birdnet-go

새, 야생 동물 및 박쥐를 위한 실시간 사운드스케이프 (soundscape) 분석기.

자가 호스팅 (Self-hosted), 24/7 가동, 로컬 AI 추론 (inference). BirdNET-Go는 사운드카드 입력 또는 네트워크 오디오 스트림을 수집하고, 멀티 모델 분류 (multi-model classification)를 실행하며, 탐지 결과를 빠른 웹 UI로 제공합니다. Raspberry Pi에서 실행 가능합니다.

멀티 모델 AI 갤러리: 앱 내부에서 재빌드 없이 BirdNET v2.4, Google Perch v2, BattyBirdNET 지역 박쥐 분류기, BirdNET Geomodel v3.0을 설치할 수 있습니다.
여러 모델을 병렬로 실행하여 별도의 오디오 소스에 적용하고, 모델 간 일치 여부를 통해 공유된 탐지 결과의 신뢰도를 높일 수 있습니다.
라이브 스펙트로그램 (spectrogram) 스트리밍 및 브라우저에서 직접 렌더링되는 **탐지 히트맵 (detection heatmaps)**을 제공합니다.
**알림 규칙 엔진 (Alert rules engine)**을 통해 탐지 결과를 Discord, Slack, Telegram, ntfy, Pushover, Gotify, Matrix, webhooks, 브라우저 푸시, MQTT (Home Assistant discovery 지원), 쉘 스크립트, BirdWeather로 전송합니다.
운영 준비 완료 (Production-ready ops): 온보딩 위저드, OIDC/SSO, TLS 인증서 관리, 핫 리로드 (hot-reload) 설정, 시스템 상태 페이지, 데이터베이스 닥터 (database doctor), 원클릭 지원 덤프 기능을 갖추고 있습니다.
PWA로 설치 가능하며, 15개의 UI 언어와 40개 이상의 언어로 된 종(species) 이름을 지원합니다.
**기본적으로 로컬 전용 (Local-only)**입니다. 선택 사항인 Sentry 텔레메트리 (telemetry)는 엄격하게 옵트인 (opt-in) 방식으로 운영됩니다.

Debian, Ubuntu, 및 Raspberry Pi OS:

curl -fsSL https://github.com/tphakala/birdnet-go/raw/main/install.sh -o install.sh
bash ./install.sh

Docker 이미지는 linux/amd64 및 linux/arm64용으로 배포됩니다.

Linux, Windows, 및 macOS용 사전 빌드된 바이너리(binaries)가 각 릴리스와 함께 제공됩니다. 자세한 내용은 설치 가이드, 하드웨어 권장 사항 및 보안 가이드를 참조하십시오.

BirdNET v2.4(기본값, 임베디드, 6,500종 이상의 조류 species)
Google Perch v2 ONNX를 통해 제공 (조류, 곤충, 양서류, 포유류를 포함한 14,795종의 species) 및 분류학(taxonomy) 기반의 species 명칭 사용
BattyBirdNET 박쥐 분류기(bat classifiers), 아프리카, 아메리카, 동아시아, 유럽, 중동, 남아시아, 동남아시아, 미국을 아우르는 11개의 지역 모델 (Linux + 초음파 지원 장치 필요)
BirdNET Geomodel v3.0 위치 기반 범위 필터링용 (12,012종)
교차 모델 탐지 합의 (Cross-model detection consensus): 모델 간의 일치 여부를 통해 신뢰도를 강화하고, 불일치하는 경우 검토를 위해 플래그를 표시함
사용자 정의 분류기 (Custom classifiers): 자체 TFLite 모델 및 레이블 세트 사용 가능
설정 가능한 오탐(false-positive) 필터링을 통한 정확한 결과 도출: Deep Detection (15초 이내 반복 확인), 종별 동적 임계값(dynamic thresholds), 위치 기반 범위 필터, 개인정보 보호 및 개 짖는 소리 필터, 분류기별 박쥐 오탐 수준(guide)

• 모델별 및 소스별 신뢰도 임계값

• 사운드카드 캡처 및 RTSP / RTSPS 스트림, 독립적인 모델 할당을 통한 여러 소스의 병렬 처리 포함

• 초음파 박쥐 탐지를 위한 최대 256 kHz의 샘플 레이트(sample rates)

• 불안정한 스트림에 대해 계층적 복구를 지원하는 오디오 라이브니스 와치독(Audio liveness watchdog)

• 스트림 샘플 레이트 프로빙(probing) 및 UI 내 모델별 권장 배너 표시

• 오디오 이퀄라이저, 소스별 정숙 시간(quiet hours), 주간 필터(daylight filter) 및 확장 캡처 모드

• 오디오 파일의 오프라인 분석

• Svelte 5 + TypeScript 기반의 싱글 페이지 애플리케이션 (Single-page app)

• 프로그레시브 웹 앱 (Progressive Web App, PWA)으로 설치 가능

• 첫 실행 설정을 위한 온보딩 위저드 (Onboarding wizard)

• 활성 스트림 (라이브 오디오 스트리밍)을 위한 실시간 스펙트로그램 (Spectrogram) 시각화

• ONNX 가속 렌더링을 적용한 탐지 히트맵 (Detection heatmaps)

• 사용자 정의 가능한 대시보드 레이아웃, 색상 구성 및 "현재 들리는 소리 (Currently Hearing)" 카드

• 탐지 목록에 대한 다중 선택 및 일괄 작업 (Bulk actions)

• 앱 내 관리를 위한 브라우저 터미널 (WebSocket 기반 xterm.js PTY)

• 15개 UI 언어 지원: 영어, 독일어, 프랑스어, 스페인어, 포르투갈어, 네덜란드어, 폴란드어, 이탈리아어, 체코어, 슬로바키아어, 헝가리어, 핀란드어, 스웨덴어, 덴마크어, 라트비아어

• 40개 이상의 언어로 제공되는 종 (Species) 이름

• 규칙별 조건, 일정 및 전달 대상(delivery targets)을 설정할 수 있는 구성 가능한 알림 규칙 엔진

• shoutrrr를 통한 다중 대상 전달: Discord, Slack, Telegram, ntfy, Pushover, Gotify, Matrix, Bark, IFTTT 등

• 사용자 정의 템플릿, 쉘 스크립트 훅 (Shell-script hooks) 및 브라우저 푸시 알림을 지원하는 웹훅 (Webhooks)

• Home Assistant 자동 검색 기능을 포함한 MQTT 발행 (Publishing)

• BirdWeather.com API 연동

• Prometheus 메트릭 엔드포인트

• 새 모이통 스트림의 OBS 오버레이를 위한 실시간 스펙트로그램 및 실시간 로그 출력

• SQLite (기본값) 또는 경합(contention) 상황을 고려한 재시도 인식 쓰기 경로를 갖춘 MySQL

• 실시간 상태 폴링을 통한 자동 백업

• 포맷 인식 오디오 클립 내보내기

• 빠른 오프라인 조회를 위한 내장 eBird/Clements 분류 체계 (2,374속, 254과, 11,145종)

• 오디오 파이프라인, 모델 및 추론 (Inference), 네트워크, 데이터 저장소를 다루는 시스템 상태 (System Health) 진단 페이지

• 진단 및 스키마 수리를 위한 데이터베이스 닥터 (Database doctor)

• 안내된 버그 보고 및 원클릭 지원 덤프를 제공하는 도움말 및 지원 페이지

• RP-Initiated 로그아웃을 포함하여 Google, GitHub 및 일반 제공자를 지원하는 OIDC / SSO

• 트랜잭션 쓰기 및 백업/복구 기능을 갖춘 TLS 인증서 관리 UI

• 설정, 모델 설치 및 소스별 모델 할당에 대한 핫 리로드 (Hot-reload, 재시작 불필요)

• 엄격한 개인정보 필터링을 적용한 선택적 Sentry 텔레메트리 (Telemetry)

• Linux, Windows, 및 macOS 지원

• BirdNET TFLite 모델이 내장된 단일 정적 바이너리 (Single static binary)

• Perch, BattyBirdNET, 및 BirdNET Geomodel v3.0을 위한 선택적 ONNX Runtime 지원 (설치 가이드 참조)

• 멀티 아키텍처 (Multi-arch) Docker 이미지

• Raspberry Pi 4 또는 그에 상응하는 64비트 싱글 보드 컴퓨터 (Single-board computer)에서 원활하게 실행 가능

• 사용자 가이드 (User guide)

• 설치 (Installation)

• 하드웨어 권장 사항 (Hardware recommendations)

• ONNX Runtime 설치

• 탐지 파이프라인 (Detection pipeline)

• 데이터베이스 닥터 (Database Doctor)

• 커스텀 분류기 학습 (Training a custom classifier)

• Cloudflare Tunnel

• 보안 (Security)

• 텔레메트리 (Telemetry) 및 개인정보 보호

• RTSP 문제 해결 (RTSP troubleshooting)

전체 가이드는 CONTRIBUTING.md를 참조하세요.

git clone https://github.com/tphakala/birdnet-go.git
cd birdnet-go
# Task 설치 (이미 설치되어 있지 않은 경우)
...

지원, 토론 및 업데이트를 위해 Discord 서버에 참여하세요.

• BirdNET-Analyzer: 업스트림 (Upstream) BirdNET 프로젝트

• BirdNET-Go Classifiers: 추가 종(species)이 포함된 강화된 BirdNET 분류기

• BattyBirdNET-Analyzer: 박쥐 분류기 모델, 앱 내 갤러리를 통해 설치 가능

• birda: BirdNET 및 Perch AI 모델을 사용하여 기존 오디오 파일에서 오프라인 조류 종 탐지를 수행하는 빠른 CLI

• birda-gui: 오디오 분석, 탐지 브라우징 및 종 시각화를 위한 birda용 데스크톱 GUI (Electron + Svelte 5)

• Cockpit BirdNET-Go: Cockpit 프레임워크를 사용하는 웹 기반 시스템 관리 플러그인

• BirdNET-Pi2Go: BirdNET-Pi에서 마이그레이션하기 위한 데이터베이스 컨버터

• BirdNET-Go ESP32 RTSP 마이크: ESP32 기반 RTSP 스트리밍 마이크

• ESP32 Audio Streamer: 대안적인 ESP32 RTSP 스트리밍 솔루션

• M5Stack Atom Echo RTSP 마이크: 납땜이 필요 없는 M5Stack Atom Echo용 RTSP 오디오 서버

• M5Stack AtomS3 Lite PDM 마이크: MEMS PDM 마이크가 탑재된 RTSP 오디오 서버

• Perch: 오픈 소스 Android/iOS 컴패니언 앱. BirdWeather API를 통해 BirdNET-Go에 연결됩니다. 실시간 탐지 피드, 오디오 재생, 종 브라우저, 14일 차트 및 즐겨찾는 종에 대한 알림을 제공합니다. MIT 라이선스입니다.

기여(Contributions)를 환영합니다.

설정, 워크플로우 및 품질 게이트(Quality gates)에 대해서는 CONTRIBUTING.md를 참조하세요:

• 요약(TL;DR) 빠른 시작: 5분 설정
• 개발 워크플로우 (Development workflow): 핫 리로드 (hot reload), git hooks, 테스트
• 라이선스 및 개인정보 보호: CC BY-NC-SA 4.0, 설계에 의한 개인정보 보호 (privacy by design)

모든 기여는 설계에 의한 개인정보 보호 (privacy-by-design) 원칙, 자동화된 코드 품질 게이트 (code-quality gates), 그리고 CC BY-NC-SA 4.0 라이선스 약관을 준수해야 합니다.

BirdNET-Go는 eBird/Clements Checklist에서 유도된 분류학 (taxonomy) 데이터를 포함합니다:

출처 (Source): eBird API v2
저작권 (Copyright): (c) Cornell Lab of Ornithology
라이선스 (License): 비상업적 목적을 위한 eBird API 이용 약관에 따라 사용됨
출처 표기 (Attribution): eBird.org에 의해 제공되는 분류학 데이터
범위 (Coverage): 2,374개 속 (genera), 254개 과 (families), 11,145개 종 (species)

자세한 내용은 eBird Taxonomy를 참조하세요.

Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International.

Tomi P. Hakala에 의해 생성 및 유지 관리됩니다.

커뮤니티 기여자들의 늘어나는 목록이 프로젝트를 계속 전진하게 합니다. 현재 목록은 GitHub 기여자 (contributors) 페이지에서 확인할 수 있습니다.

BirdNET AI 모델은 Chemnitz University of Technology (Stefan Kahl, Connor Wood, Maximilian Eibl, Holger Klinck)와의 협업을 통해 Cornell Lab of Ornithology의 K. Lisa Yang Center for Conservation Bioacoustics에서 제작되었습니다.

Justin Chuby의 Google Perch v2 ONNX 변환. R.D. Zinck의 BattyBirdNET 박쥐 분류기 (bat classifier) 모델. Patrick McGuire의 BirdNET-Pi 프로젝트를 위한 Patrick Levin의 BirdNET 레이블 번역.