Building Dawn Chorus: a Local Gemma Walk Companion, Offline Birdsong ID with BirdNET, and Mock Testing

ajaypraneeth15 — Wed, 07 Oct 2026 15:49:29 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass

What I Built

Dawn Chorus is an offline bird-call identifier with an unusual goal: the AI should make you use your phone less, not more.

You run plan and get a printable bingo card of birds that are plausible at your location this week. You take the paper card outside, listen, and tick squares in pencil with the phone in your pocket. Back home, listen runs your voice memo through the model, writes illustrated field notes, and adds new species to a life list stored in SQLite on your own computer. Two optional features use a Gemma model running locally in Ollama: before you go, companion is a short chat that reads this week's bingo card and your life list, suggests a walk mission, and then tells you to put the phone away; and after the walk, listen --journal writes a short journal entry at the top of the notes.

Everything runs on your machine: no account, no API key, no upload. A trail recording can contain conversations, children's voices and clues about where you are, so it shouldn't have to leave your computer. And birding often happens where there's no signal.

The part I'm proudest of is less glamorous: the Ollama integration is tested without Ollama. More on that below.

Demo

Dawn Chorus runs on your own computer, so there is no hosted demo to click. These are screenshots from my own Windows PC, with the official two-minute BirdNET example recording (it was recorded in New York, so I used New York coordinates) and gemma3:4b running locally in Ollama.

1. listen --journal: BirdNET finds three species in 1.5 seconds, and Gemma is asked to write the journal entry.

2. The field notes page it wrote. The boxed paragraph at the top is Gemma's, labelled as AI-written. The list and the confidence bars below it are BirdNET's.

3. The walk companion. I asked what to bring and it answered in one short sentence. (The second message is a command I pasted into the chat by accident. Gemma treated it as a message and still pointed me outside.)

4. What the printable pieces look like. The bingo card is the page you print and take outside, and this is the field notes page layout. These two sample images were generated from the repository's own sample data.

The text of the companion's opening mission and of the journal paragraph is quoted further down, in Running it on my own Windows PC.

Code

ajaypraneeth15 / dawn-chorus

Dawn Chorus – Open Source Birdsong & Audio Analyzer

An offline bird-call identifier that exists to get you off the screen.

You print a bingo card of the birds likely where you are this week, go stand outside with your phone in your pocket, record a few minutes of what you hear, and check your ears against the model when you get home. Identification, the location model, and your life list all run on your own machine. No account, no API key, no cloud.

The optional extras, a local Gemma model that acts as your walk companion and writes a short field-journal entry, talk only to Ollama on your own computer.

Overview and the problem it solves

Most AI…

View on GitHub

How I Built It

I built this in one session with Claude, Anthropic's AI coding agent, so "we" below means the two of us. I gave Claude the challenge brief; Claude wrote the code and ran every test described here in its own cloud sandbox. Claude's sandbox could not reach Ollama, so Claude tested the Gemma code against stand-ins (see Testing). I then ran doctor, plan, listen, companion and listen --journal on my own Windows PC, with a real gemma3:4b through Ollama (see Running it on my own Windows PC).

Claude is only the builder: nothing in Dawn Chorus calls Claude or any hosted API when it runs.

Who does what

It helps to be precise about which model does which job, because "AI" covers several different things here:

Job	Model	Where it runs
Identify birds in audio	BirdNET V2.4 (open-weight classifier)	Your CPU, via Google's LiteRT/TFLite runtime
Decide which birds are plausible here and now	BirdNET location model	Your CPU
Chat before the walk (`companion`) and write a short journal paragraph (`--journal`)	Gemma (optional)	Your computer, served by Ollama

Gemma never hears the audio. It only sees short text lists: the bingo card, or the species BirdNET already found. So the bird identifying is BirdNET's job, and Gemma's is the talking and writing.

The stack is Python, numpy, ai-edge-litert, ffmpeg, SQLite, and the standard library's urllib for talking to Ollama. I did not use Librosa or requests: ffmpeg decodes the audio to 48 kHz mono, and urllib is enough for three small HTTP calls. That keeps the install to three pip packages.

Technical architecture

                    Dawn Chorus
                         |
             +-----------+-----------+
             |                       |
        Audio recording        Location + week
        (ffmpeg decode)                |
             |                       v
             v              BirdNET location model
      BirdNET audio model     "which species are
      (3 s windows)            plausible here?"
             |                       |
             +-----------+-----------+
                         |
                         v
              Detections (local only)
                         |
          +--------------+--------------+
          |              |              |
     Field notes     Life list      (optional)
     (HTML)          (SQLite)       Gemma journal
                                    via local Ollama

  Before the walk:  bingo card + life list --> Gemma companion (local Ollama chat)

Listening. Audio is split into three-second windows, each run through the BirdNET classifier. We keep detections above a confidence threshold (default 0.5) that the location model also considers plausible for the place and week.

Location awareness, twice. The location model filters listening results, and it also builds the bingo card. On the official BirdNET example recording, low-confidence guesses like Hawfinch and Chestnut-winged Cuckoo disappear under a New York location.

A real bug, found because the model is open. BirdNET has seven non-bird labels: Engine, Dog, Siren, Gun, Fireworks, Noise and Environmental. The first test run reported "Engine" as a new species for the life list. Because the label file and raw outputs are accessible, we masked those classes out and added a test.

Offline for real. scripts/offline_check.sh runs the whole pipeline inside a Linux network namespace whose only interface is loopback, so anything that tried to phone home would fail. Planning and identification both pass there.

The Ollama integration: `ollama_journal`

The function talks to Ollama's REST API on http://127.0.0.1:11434 using only the standard library. Here is the heart of it, trimmed for the article:

def ollama_journal(dets, *, place, when, model=None, host=OLLAMA_DEFAULT_HOST, timeout=180):
    # Never route traffic for this same computer through an HTTP proxy.
    opener = urllib.request.build_opener(urllib.request.ProxyHandler({})) if _is_local(host) \
        else urllib.request.build_opener()
    ...
    if not model:
        names = [m.get("name") for m in call("/api/tags").get("models", []) if m.get("name")]
        model = next((n for n in names if "gemma" in n.lower()), names[0])  # prefer Gemma if installed
    out = call("/api/generate", {
        "model": model, "prompt": journal_prompt(dets, place=place, when=when), "stream": False,
        "options": {"temperature": 0.4, "num_predict": 260}}, t=timeout)

A few design decisions:

Gemma first, with a graceful fallback. With no --ollama-model, the tool lists installed models and picks the first one with gemma in its name (case-insensitive). If there is none, it uses the first model Ollama lists. An explicit --ollama-model always wins and skips the lookup.
A fenced-in prompt. The prompt contains only the species list, place and date, and says to use only those facts and not to invent behaviour. A small model can still be wrong, so the page labels the paragraph as AI-written and the detection list stays the record. The model's text is HTML-escaped before it reaches the page.
It fails soft. If Ollama isn't running, the model isn't pulled, the request times out, or the answer is empty or garbled, the tool raises a friendly OllamaError, prints journal skipped: ... and still writes the notes. An unknown model gets an ollama pull <model> hint.
Local by default. If you point --ollama-host at another machine, the tool prints a notice that your detections will be sent there.

The Gemma companion

The most important design question was how to use a chat model in an app whose whole point is to get you away from the screen. A chatbot that keeps you talking would defeat it. So companion is built to end:

python3 dawn_chorus.py companion --lat 42.45 --lon -76.50 --place "Cayuga Lake trail"

It starts with a mission, not a greeting. The first message is generated for you: a short walk mission built from this week's bingo card.
It is short on purpose. Replies are limited to about three sentences, the number of turns is capped (default 4, maximum 10), and an empty line or go ends the chat. The program, not the model, prints the closing line: "Time to go outside. Phone in your pocket..." and the command to run when you are back.
It is grounded in facts we really have. The system prompt holds today's date and week, your place, the 24 birds on the card with how likely each is this week (from the BirdNET location model), and your life-list size and latest additions. The model is told it may mention only those birds and must not describe their songs, looks or habitat, because a small model can be confidently wrong about birds. General tips, like standing still and listening for five quiet minutes, are fine.
It fails soft. If Ollama isn't running you get a friendly message that points to plan, which needs no language model. If the connection drops mid-chat, the chat ends politely.
Language. --language Tamil (or any language name) is added to the instructions. I speak Tamil, and Gemma lists many languages, but I have not tested how good a small model is in Tamil.

The conversation loop is a small pure function, which is what makes it testable without a model:

def companion_session(chat, system, *, turns, once, ask, say):
    messages = [{"role": "system", "content": system}, {"role": "user", "content": MISSION_REQUEST}]
    ...
    for _ in range(max(0, turns)):
        text = ask("you> ").strip()
        if text.lower() in END_WORDS:      # "", "go", "bye", "quit", ...
            break
        messages.append({"role": "user", "content": text})
        turn()                             # POST /api/chat with the whole history

Testing without Ollama

A test suite that needs a running LLM server, a multi-gigabyte download and a GPU is a test suite nobody runs. So the Ollama code is tested three ways, and none of them needs Ollama:

1. A stand-in server (26 tests in tests/test_dawn_chorus.py, including Windows-portability checks). A tiny FakeOllama HTTP server starts on a free local port and speaks the real protocol (/api/tags, /api/generate). This exercises the actual urllib code, headers and JSON parsing end to end, alongside the BirdNET geography tests and a real-audio run.

2. unittest.mock (24 tests in tests/test_ollama_mock.py). Here the HTTP layer is replaced by a mock opener, and a guard patches socket.socket.connect so that any accidental real network call fails the test:

class NoRealNetwork(unittest.TestCase):
    def setUp(self):
        guard = mock.patch("socket.socket.connect",
                           side_effect=AssertionError("real network call attempted"))
        guard.start()
        self.addCleanup(guard.stop)

On top of that, tests cover:

the request is a POST to /api/generate with the chosen model, stream: false and a prompt listing the detected birds;
Gemma priority: Gemma beats models listed before it, matching ignores case, the first Gemma wins when several are installed, no Gemma falls back to the first model, and an explicit model skips the lookup;
failure modes: connection refused, timeout, 404 (with the pull hint), 500 (without it), no models, empty answer, missing response field, garbled JSON;
staying local: loopback bypasses system proxies, remote hosts are flagged, and requests, librosa and urllib.request aren't even imported until --journal is used;
prompt safety: only detected birds appear in the prompt, and <img src=x onerror=...> in model output is escaped.

3. The companion (22 tests in tests/test_companion.py). The /api/chat client is tested with the same mock opener. The conversation loop is tested with scripted inputs: the opening mission, the whole history reaching the model, the turn cap holding even if the person keeps typing, quitting on an empty line or bye, Ctrl+C and end-of-input, and Ollama disappearing mid-chat (the failed turn is removed from the history). The system prompt is tested for what it must contain (all 24 card birds, the likelihood words, the rules) and what it must not (birds that aren't on the card). Finally, the companion command runs end to end against the stand-in server.

I also mutation-checked the suite: breaking the Gemma preference, the fallback model, stream: false, the turn cap, the endpoint, or the card contents each makes tests fail, which is how you know the assertions aren't decorative.

CI/CD

Because nothing needs a network or a model server, the whole suite (72 tests, about 12 seconds on Claude's sandbox, including real-audio inference) can run on a plain CI runner. Here is a GitHub Actions workflow you could drop into .github/workflows/test.yml. It's a suggestion: I haven't run it on GitHub Actions.

name: tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: sudo apt-get install -y ffmpeg
      - run: pip install numpy ai-edge-litert && pip install --no-deps birdnetlib
      - run: python -W error::ResourceWarning -m unittest discover -s tests -v

Testing, honestly

Tested, by Claude in its sandbox:

72 automated tests pass (26 with the stand-in server, 24 with unittest.mock, 22 for the companion).
End-to-end identification on the official two-minute BirdNET example soundscape, in about 1.5 seconds on a 2-vCPU machine with no GPU. That's one machine, so I'm not claiming the same speed everywhere.
The full pipeline with the network disabled.
scripts/check_ollama.sh against a fake Ollama server in five situations (Gemma installed, no Gemma, no models, a -cloud model, server down), with the expected exit code each time.

Not tested yet: a phone recording from a real walk, Raspberry Pi, macOS, the companion in Tamil, and the repository's .bat helper files (I ran the commands by hand on Windows instead). Claude's sandbox never ran a real Gemma model; the real runs below are mine, on my own PC. The mock and stand-in tests prove the client code and the conversation logic are right; they say nothing about how helpful or accurate a Gemma model is, which is why I ran a real one.

Real Gemma runs (mine, on my own PC, gemma3:4b through Ollama): the sections below show exactly what came out, including where it slipped.

Running it on my own Windows PC

The code was written and tested on Linux, so I ran it on my Windows PC (Python 3.14) to find out what happens. BirdNET runs on the CPU there (TensorFlow Lite's XNNPACK delegate). Results, from my own screen:

python dawn_chorus.py doctor loads both BirdNET models (6,522 species), in 0.30 s on one run and 1.65 s on a later one (timings vary from run to run), with one audio window plus a location lookup taking 42 to 58 ms, and reports no network modules imported.
python dawn_chorus.py plan generated a bingo card: "24 targets, 75 species plausible at 42.45,-76.50 in week 37/48". For my own town, Batticaloa in Sri Lanka (--lat 7.71 --lon 81.69), it gave "24 targets, 222 species plausible ... in week 37/48".
python dawn_chorus.py listen on the official two-minute BirdNET example recording (it was recorded in New York, so I used New York coordinates) took 1.9 s and then 1.5 s on a second run, for 40 three-second windows. It found three species: Black-capped Chickadee (81%), Dark-eyed Junco (74%) and House Finch (64%). I did not check these by ear; they are BirdNET's detections.
ffmpeg is needed to decode audio. winget install Gyan.FFmpeg was a 245 MB download, and I had to restart my shell before the command was found.

Two Windows-only problems came up:

The AI runtime would not load. ai-edge-litert installed fine, but importing it failed with DLL load failed ... The specified module could not be found. I opened the package's Windows files and its DLLs import MSVCP140.dll and VCRUNTIME140_1.dll, which come from the Microsoft Visual C++ Redistributable. Installing it (winget install Microsoft.VCRedist.2015+.x64) fixed it. The tool now prints the real import error instead of a bare "install ai-edge-litert", and the Windows setup helper explains this fix.
A date format Windows rejects. Reading the code for Windows problems showed strftime('%-d') in three places. Windows raises ValueError for it, which would have crashed plan and listen. It is replaced by a small helper, and tests simulate the Windows behaviour on any platform.

The companion, with a real Gemma

I pulled gemma3:4b (3.3 GB) and ran companion --lat 7.71 --lon 81.69 --place "Batticaloa". Its opening mission was:

Let's see if we can spot a White-throated Kingfisher today – they're looking good this week. Head out and see if you can find one near the water!

Checking it against the card: the White-throated Kingfisher really is on my Batticaloa card, marked "likely", so "looking good this week" matches the data. But "near the water" is a habitat remark, which the prompt tells the model not to make. It is a small slip, and a good example of why I kept the instructions strict and the replies short. I then asked "what should I bring?" and it said:

Just a bottle of water and a notebook to jot down any sightings – that's all you need for a pleasant walk.

That is a safe, general tip, which the prompt allows. By accident I also pasted a shell command into the chat. Gemma treated it as a message and still steered me outside ("Find a quiet spot and just listen for a few minutes"). Pressing Enter on an empty line ended the session, and the program printed the closing "Time to go outside" lines and (chatted with gemma3:4b, running on this computer). I did not measure how long each reply took.

The journal, with a real Gemma

listen examples\soundscape.wav --lat 42.45 --lon -76.50 --journal --ollama-model gemma3:4b wrote this into the field notes page (the program labels it "written by gemma3:4b, running locally in Ollama" and "AI-written from the detections below. It can be wrong; the list is the record"):

The automatic detections picked up a Black-capped Chickadee early in the recording, a brief but clear signal. Later, a House Finch was identified in several short segments, though the confidence level was lower. Finally, a Dark-eyed Junco was detected twice, offering a slightly more reliable identification.

I checked it against the list below it. The Chickadee was heard once at 0:00 (81%), the House Finch three times (first at 0:09, 64%) and the Junco twice (74%), so the counts and the "lower" and "more reliable" comparisons are right, and it names no bird that BirdNET did not detect. It is flat rather than lovely, and "clear signal" is the model's own embellishment. I would not call that great writing, but it is faithful, which is the thing a small local model can promise here. This is one run, not an evaluation.

How to Try It

git clone https://github.com/ajaypraneeth15/dawn-chorus.git
cd dawn-chorus
pip install numpy ai-edge-litert
pip install --no-deps birdnetlib          # carries the BirdNET weights (~66 MB)
sudo apt install ffmpeg                   # or: brew install ffmpeg

python3 -m unittest discover -s tests -v  # no Ollama needed
sh scripts/get_example_audio.sh           # fetch the example recording
python3 dawn_chorus.py plan --lat 42.45 --lon -76.50 --place "Cayuga Lake trail"
python3 dawn_chorus.py listen examples/soundscape.wav --lat 42.45 --lon -76.50

To add Gemma (the model download is a few gigabytes, so mind your data; my gemma3:4b was 3.3 GB):

ollama serve                    # the desktop app does this for you
ollama pull gemma3:4b           # what I used; gemma3:1b is smaller but I have not tried it. Tag names change; check https://ollama.com/library
bash scripts/check_ollama.sh    # is Ollama up, and is a Gemma model installed?
python3 dawn_chorus.py companion --lat 42.45 --lon -76.50                       # chat before the walk
python3 dawn_chorus.py listen examples/soundscape.wav --lat 42.45 --lon -76.50 --journal   # journal after

On Windows, use python instead of python3, install the Visual C++ Redistributable if the AI runtime won't load, and the repository's windows folder has double-click .bat helpers (setup, check, plan, demo, Gemma, tests, companion). Those helpers have not been run by anyone yet.

Model names on Ollama change over time, so use ollama list to see what you have. A model whose name ends in -cloud runs on Ollama's servers, not on your computer, so pick one without that suffix for a fully local run.

Why Does Open Innovation Matter?

It works without the internet. A cloud-only identifier fails exactly where birders go. Here the models run locally, and offline operation was tested, not just promised.
Recordings stay on your machine. With local inference there's no need to upload anything. The notes and life list stay local too, and the optional Gemma step talks only to Ollama on 127.0.0.1.
We could inspect and fix the model's behaviour. A closed bird-ID API might simply return "Engine" as a bird. With open files we found the seven non-bird classes, masked them, and wrote a test.
We could reuse one model for a different purpose. The location model that filters results also builds a physical bingo card before you leave home. One open capability now covers planning, going outside and identifying, and the app gets out of the way during the walk.
No per-call cost. No API keys, quotas or inference charges, which makes experimenting easy.
Light enough for an ordinary PC. On my Windows PC, loading both BirdNET models took between 0.3 and 1.7 s and a window plus location lookup 42 to 58 ms across two runs. I have not measured energy use, so I am not making claims about it.

A note on licensing

Dawn Chorus's code is MIT. The BirdNET weights are CC BY-NC-SA 4.0: free to use and modify, but not for commercial use, which is why I call BirdNET open-weight instead of claiming it shares my code's license. Gemma is used under Google's Gemma terms and is downloaded by you through Ollama.

BirdNET is by Kahl, Wood, Eibl & Klinck (Cornell Lab of Ornithology and Chemnitz University of Technology), Ecological Informatics 61, 101236 (2021).

My Agent Session

I built this project myself, with minimal assistance from Claude. I used Claude mainly for guidance and support in areas of the process that I wasn’t familiar with, from reviewing the challenge brief to testing, packaging, and writing this post.

What's Next

The first job is a real walk: record a phone soundscape, run it through listen, and compare against what I can identify myself. After that: a systematic check of how helpful a real Gemma companion is over many runs (including in Tamil, which I have not tried), macOS and Raspberry Pi testing, and fine-tuned BirdNET models for local birds.

The idea to keep is simple: use AI to make the screen less important. Print the card. Put the phone away. Go outside. 🐦🌿

Prize Categories

Gemma. Dawn Chorus uses Gemma, Google's open-weight model, running locally through Ollama, as a short outdoor companion before the walk (companion, using POST /api/chat) and to write the optional journal entry in the field notes (listen --journal). The integration is in dawn_chorus.py (ollama_chat, companion_session, ollama_journal), with dozens of tests and a preflight script, and it is documented in the README. I ran both features myself with a real gemma3:4b on my own computer, and the output, including a small rule slip, is shown above.

DEV Community: ajaypraneeth15

Building Dawn Chorus: a Local Gemma Walk Companion, Offline Birdsong ID with BirdNET, and Mock Testing

What I Built

Demo

Code

ajaypraneeth15 / dawn-chorus

Dawn Chorus – Open Source Birdsong & Audio Analyzer

Contents

Overview and the problem it solves

How I Built It

Who does what

Technical architecture

The Ollama integration: `ollama_journal`

The Gemma companion

Testing without Ollama

CI/CD

Testing, honestly

Running it on my own Windows PC

The companion, with a real Gemma

The journal, with a real Gemma

How to Try It

Why Does Open Innovation Matter?

A note on licensing

My Agent Session

What's Next

Prize Categories

DEV Community: ajaypraneeth15

Building Dawn Chorus: a Local Gemma Walk Companion, Offline Birdsong ID with BirdNET, and Mock Testing

What I Built

Demo

Code

ajaypraneeth15 / dawn-chorus

Dawn Chorus – Open Source Birdsong & Audio Analyzer

Contents

Overview and the problem it solves

How I Built It

Who does what

Technical architecture

The Ollama integration: ollama_journal

The Gemma companion

Testing without Ollama

CI/CD

Testing, honestly

Running it on my own Windows PC

The companion, with a real Gemma

The journal, with a real Gemma

How to Try It

Why Does Open Innovation Matter?

A note on licensing

My Agent Session

What's Next

Prize Categories

The Ollama integration: `ollama_journal`