birdjournal: A Fully Offline Open-Source AI Bird Sound Identification Tool — Analysis and Testing

When it comes to birdwatching, most apps require you to stare at a screen, upload recordings to the cloud, and create an account. birdjournal, built by developer kavyansh-1 for the Hacktoberfest open-source AI challenge, takes the opposite approach: record the birdsong, put your phone away, look up at the sky, and let local open-source AI handle the rest. No internet connection, no account, no cloud — and it can even auto-generate a birding journal entry in English, Hindi, or Punjabi.

What Problem Does It Solve

birdjournal positions itself as an "offline birdsong field journal." The author's design philosophy is clear — the screen should be the shortest part of the entire experience: you start recording, head outdoors, look up and observe, and the identification and writing happen entirely afterward.

This targets beginner birdwatchers and anyone who has ever heard a bird and wondered what it was. The key is that it works whether or not you have a signal. For birdwatchers who regularly venture into mountainous terrain or dead zones, this is a real pain point that mainstream cloud-based identification apps simply cannot address.

Technical Architecture: BirdNET + Local LLM

birdjournal's pipeline is straightforward, built by chaining two open-source components:

Phone recording (.wav/.mp3)
      ↓
BirdNET (open-source) —— geographic filter (lat/lon) removes species not present locally
      ↓
Species list + confidence scores
      ↓
Local LLM running via Ollama (open weights)
      ↓
Short field journal entry (English / Hindi / Punjabi / ...)

Sound identification is handled by BirdNET. The author uses its litert backend, meaning no TensorFlow installation is required — it can even run on a Raspberry Pi. BirdNET's geographic model reads your latitude and longitude and automatically filters out species that wouldn't appear in your area, significantly reducing false positives.

Journal writing is delegated to an open-weight model loaded via Ollama, defaulting to Qwen2.5 3B. A simple --model flag lets you swap in any other local model. The author also tested Gemma 3 4B running the same codebase.

The Python glue layer connects everything: detector.py runs BirdNET and groups detections by species, journal.py sends prompts to the local LLM, and main.py serves as the command-line entry point. Even if Ollama isn't running, it will still print the species list and a plain-text summary. The entire project is open-sourced under the MIT license.

BirdNET is a deep learning bird sound recognition model jointly developed by the Cornell Lab of Ornithology and Chemnitz University of Technology in Germany. Built on an EfficientNet architecture, it was trained on audio data covering approximately 6,000 bird species worldwide. It works by slicing audio into 3-second windows and outputting a species probability distribution for each segment. litert (formerly TensorFlow Lite Runtime) is a lightweight inference backend from Google optimized for edge devices. It strips away the heavy dependencies of the full TensorFlow framework, compressing model size to tens of megabytes, enabling direct deployment on low-power devices like Raspberry Pis and smartphones. Ollama is a local LLM runtime framework that provides a unified REST API, allowing developers to call locally running open-weight models as if they were cloud services — without worrying about model loading, quantization, or memory management. A single command is all it takes to switch between models.

Real-World Testing: The Coppersmith Barbet Case

The author tested with a 46-second recording from Sikar, Rajasthan (sourced from Xeno-canto, recorded by Dipendra Maharshi, CC BY-NC-SA 4.0), featuring the call of the Coppersmith Barbet.

Species heard: 1
  Coppersmith Barbet           x16  best 100%  first at 0s

With the geographic filter locked to Sikar, BirdNET identified the barbet in all 16 three-second windows with 100% confidence. The author candidly notes this was a clean, loud, single-species sample — "an easy pass, not a measure of accuracy." A proper field test — recording a dawn chorus with real background noise near Patiala — has yet to be conducted.

The Hallucination Trap in Small Models

The most valuable part of this write-up is the author's honest account of failures encountered when small models went off the rails while generating journal entries.

The first prompt version caused the model to fabricate details not present in the detection results — describing the barbet as "colorful and melodious," when its call is actually closer to a steady "tuk-tuk-tuk." The model also misread "16 three-second audio windows" as "heard 16 times." The author then tightened the prompt, enforcing exactly three first-person sentences based strictly on the listed facts.

Switching to Gemma 3 4B exposed two new bugs: the model wrote the literal letter "N" instead of a number, and described a 100% confidence detection as "uncertain." The author's key fix was to move the "certain/uncertain" logic from the prompt into the code itself. Even so, a second run still had residual issues: the model wrote "16 Coppersmith Barbets," when the actual meaning was 16 audio windows.

"A 4B model can follow rules but will still blur these details, which is exactly why I treat the journal as a rewrite of BirdNET's output rather than a source of truth."

This lesson is broadly applicable to any developer using small models for structured rewriting: don't let the language model carry the burden of judgment — keep deterministic logic in code, and let the LLM handle only the phrasing.

"Hallucination" refers to language models generating content that is linguistically fluent but factually inconsistent with the input — an inherent characteristic of all LLMs, and especially pronounced in smaller models (3B–4B scale). The root cause is that LLMs are trained to predict the probability distribution of the next token, not to verify the truth of propositions — the model "doesn't know what it doesn't know." This makes them particularly error-prone with structured numerical data: numbers, units, and counting logic all fall outside the pattern-matching sweet spot of language models. Moving the "certain/uncertain" logic from the prompt into code is essentially an application of a core engineering principle: any logic with a clear, deterministic criterion should not be delegated to a probabilistic model. Use code's deterministic computation to pre-process such decisions, then pass the results to the LLM in clear natural language — letting it do only what it does best: rewriting and polishing.

Why Open-Source and Offline Matter

The author makes four arguments for the value of this open-source, offline approach:

• Works without a signal. The two models are approximately 77 MB and 46 MB — download once, cache locally, and no network is needed along the entire trail. Cloud-based identification apps can't say the same.
• Recordings stay on your device. No audio is ever uploaded.
• Free to run. No per-call API fees. You can record an entire morning without worrying about costs.
• Self-serviceable. When the journal model starts hallucinating, the author can directly edit the prompt or swap models with a single parameter. With a closed-source API, you're stuck accepting whatever output you get.

Limitations are also honestly listed: BirdNET's training data skews toward Europe and North America, with limited South Asian species coverage, leading to missed detections in countries like India. A single clean recording is an easy test that doesn't represent real-world accuracy. And the journal entries are simply rewrites of BirdNET output — they still need to be cross-checked against what you actually observed.

Conclusion

birdjournal isn't a project chasing technical showmanship. It's more of a grounded exploration of the "local-first AI" philosophy: use a mature open-source classifier (BirdNET) for hard decisions, use a local small model for soft expression, and keep a clear boundary between the two. It's competing for the "Best Use of Gemma" award, but the more transferable insight is the author's clear-eyed understanding of small model limitations, and the deliberate prioritization of offline capability, privacy, and controllability as core design principles.