# BirdNoises — Full Technical & AI Agent Reference (`llms-full.txt`)

> **BirdNoises** (`https://birdnoises.com`) is an interactive 6,511-species bird soundboard, wild field recording streamer, offline dual-bronchial syrinx synthesizer, and multi-track Dawn Chorus studio. Created by **Putervision** (`https://putervision.com`) and paired with **BirdHear** (`https://birdhear.com`).

---

## 1. Application Overview & Architecture

- **Production URL**: `https://birdnoises.com/`
- **Deep-Link URL Pattern**: `https://birdnoises.com/?species={Scientific_or_Common_Name}` (e.g., `https://birdnoises.com/?species=Gavia_immer` or `https://birdnoises.com/?species=Cardinalis_cardinalis`)
- **Sibling Application**: `https://birdhear.com/` (AI Bird Sound Identifier & Unattended 48 kHz Clip Vault)
- **Publisher**: Putervision (`https://putervision.com`)
- **Contact**: `contact@birdnoises.com` / `contact@birdhear.com`
- **Runtime**: Client-side Progressive Web App (PWA) with offline Service Worker caching (`ngsw.json`), Web Audio API dual-syrinx FM/AM synthesis, CORS HTMLAudioElement streaming from iNaturalist Sounds and Wikimedia Commons Audio, and `48,000 Hz` mono WAV export.

---

## 2. Public Data Endpoints (Static JSON & Audio)

AI agents and HTTP clients can fetch the following static resources directly without authentication (`Access-Control-Allow-Origin: *`):

1. **`GET /data/labels.json`**
   - **Content-Type**: `application/json`
   - **Description**: Array of `6,522` strings (`6,511` bird species + `11` non-bird classes) formatted as `"Scientific Name_Common Name"` (e.g., `"Cardinalis cardinalis_Northern Cardinal"`, `"Gavia immer_Common Loon"`).
2. **`GET /audio/sample.wav`**
   - **Content-Type**: `audio/wav`
   - **Description**: Reference `48,000 Hz` mono WAV bird vocalization recording.
3. **`GET /openapi.json`**
   - **Content-Type**: `application/json`
   - **Description**: OpenAPI 3.1.0 specification describing all static endpoints, query parameters, and schemas.
4. **`GET /.well-known/agent.json` (or `GET /agent.json`)**
   - **Content-Type**: `application/json`
   - **Description**: Machine-readable AI Agent Card describing capabilities, skills, DOM selectors, and the `window.birdnoisesAgent` JavaScript bridge.

---

## 3. Programmatic Browser Agent API (`window.birdnoisesAgent`)

When inspecting or automating BirdNoises in a browser environment (Playwright, Puppeteer, Selenium, Chrome Extension, WebMCP, or Computer Use), use `window.birdnoisesAgent`:

### Methods

```ts
interface BirdNoisesAgentBridge {
  /** Returns application metadata, species count, and available agent methods */
  getAppInfo(): {
    name: 'BirdNoises';
    url: 'https://birdnoises.com';
    publisher: 'Putervision';
    publisherUrl: 'https://putervision.com';
    siblingUrl: 'https://birdhear.com';
    contactEmails: ['contact@birdnoises.com', 'contact@birdhear.com'];
    totalSpecies: number;
    categories: string[];
    methods: string[];
  };

  /** Returns live playback, active species, source mode, and chorus mixer status */
  getStatus(): {
    isLoadingTaxonomy: boolean;
    totalSpecies: number;
    filteredCount: number;
    activeCategory: string;
    searchQuery: string;
    sourceMode: 'wild' | 'synth';
    activeCallType: 'song' | 'call' | 'trill' | 'drum';
    isPlaying: boolean;
    activeSpecies: {
      commonName: string;
      scientificName: string;
      birdType: string;
      baseFreqHz: number;
    } | null;
    activeRecordingMeta: {
      source: string;
      recordist: string;
      license: string;
      url: string;
    } | null;
    chorusRunning: boolean;
    chorusTrackCount: number;
  };

  /** Searches the 6,511 species catalog and updates the UI search filter */
  searchSpecies(query: string, limit?: number): Array<{
    commonName: string;
    scientificName: string;
    birdType: string;
    baseFreqHz: number;
  }>;

  /** Selects one of the 12 bird decks ('all' | 'featured' | 'songbirds' | 'warblers' | 'cardinals' | 'corvids' | 'owls' | 'raptors' | 'woodpeckers' | 'waterfowl' | 'shorebirds' | 'hummingbirds' | 'parrots' | 'doves') */
  selectCategory(categoryId: string): void;

  /** Finds a species by scientific or common name and plays its vocalization */
  playSpecies(
    queryOrName: string,
    callType?: 'song' | 'call' | 'trill' | 'drum'
  ): Promise<boolean>;

  /** Switches between 'wild' field recordings and 'synth' dual-syrinx synthesis */
  setSourceMode(mode: 'wild' | 'synth'): void;

  /** Sets the active vocalization pattern ('song' | 'call' | 'trill' | 'drum') */
  setCallType(callType: 'song' | 'call' | 'trill' | 'drum'): void;

  /** Loads and starts a multi-bird Dawn Chorus preset ('dawn' | 'nocturnal' | 'wetland' | 'tropical') */
  startChorusPreset(preset: 'dawn' | 'nocturnal' | 'wetland' | 'tropical'): void;

  /** Stops all active bird vocalization playback and chorus mixer tracks */
  stopAllAudio(): void;
}
```

---

## 4. Semantic DOM Selectors (`data-agent-action`)

For visual/DOM browser agents that click or type into elements directly:
- `[data-agent-action="search-species"]` — Search input for filtering the 6,511 species catalog
- `[data-agent-action="mode-wild"]` — Switch to Wild Field Recordings audio mode
- `[data-agent-action="mode-synth"]` — Switch to Offline Dual-Syrinx Synthesizer audio mode
- `[data-agent-action="play-active-pad"]` — Play or stop the active studio bird pad
- `[data-agent-action="export-wav"]` — Export a 3.0s 48 kHz mono WAV file for the active bird
- `[data-agent-action="toggle-chorus-drawer"]` — Open or close the multi-bird Dawn Chorus mixer drawer
- `[data-agent-action="install-pwa"]` — Trigger PWA install flow or instructions modal