Skip to content

Latest commit

 

History

History
63 lines (50 loc) · 3.53 KB

README.md

File metadata and controls

63 lines (50 loc) · 3.53 KB
Raw

BirdSong

An app to quiz yourself on bird identification by song.

I made this app because I work from home and usually sit on my deck in my backyard when the weather is nice. I hear lots of birds, and I know the usual suspects very well, but every now and then I'll hear one that I don't recognize, and by the time I've run inside to get my Sibley book, they're often gone. I realized that I wanted an easy way to learn the bird songs in my area without putting in hours and hours of field work 😅. When I went looking for this, I couldn't find what I wanted, so I figured I had to build it!

The UI is a bit rough at the moment - I am focused more on functionality than looks right now. I'm using a UI framework called DaisyUI that gives me a little bit of style, but I would love to work with a designer at some point to give it some real polish.

UI Features

  • Uses recordings from Cornell's Macaulay Library
  • Enter a specific region to hear birds from (country, state, or county)
  • Optionally limit to only certain species groups
  • Optionally show images alongside recordings (images are sourced from flickr.com)
  • Bird's name is hidden until user clicks to reveal it

Future Feature ideas

  • use browser location
  • enable user to change filters from quiz interface
  • enable user to input which bird they think it is
  • track correct answers in a session
  • track correct answers over time
  • verbal descriptions of distinguishing physical characteristics
  • verbal descriptions of songs & calls
  • filter by individual species

TODO

  • use browser location
  • show image attribution
  • filter by recently observed birds
  • filter by recent notable observations in a region
  • enable user to enter any location by text
  • filter by individual species
  • use XC + Ebird for recordings?
  • use Ebird for images? (pro - better images, con - no API)
  • fix broken tests
    • quiz_live_test
    • services_test
    • record_data_test
    • count_data_test
  • use struct for assigns in LiveView
  • show recording attribution
  • filter by species group
  • enable user to enter any location by code
  • ‼️ Playwright ports are not getting shutting down on exit

Data Features

  • Written in Elixir, and uses Phoenix's LiveView framework for the front-end
  • Uses ETS tables to cache data
  • Uses GenServers to throttle external data requests to no more than 1 request per second
  • Uses Playwright (via an Elixir port) to crawl the Macaulay Library site for recordings, since they do not have an API
  • Currently writes new JSON responses to .json files and loads them into ETS tables on startup, instead of using a database. My reasoning for this is that I am trying to plan for how to seed the database when I eventually push this to production. There is a LOT of data to seed: 16,847 known species in the world, multiplied by 4 API requests each (1 for images and 3 for recordings). Because requests are rate-limited, it takes hours to collect a full data set, and the collection task often goes down and needs to be restarted. It seems best to write everything to disk for now, but I may change this in the future.

Running locally

To start your Phoenix server:

  • Install dependencies with mix deps.get
  • Create and migrate your database with mix ecto.setup
  • Start Phoenix endpoint with mix phx.server or inside IEx with iex -S mix phx.server

The main page is located at localhost:4000/quiz.