# nishantnnb/spectrolipi architecture

> Architecture diagram of the GitHub repository nishantnnb/spectrolipi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nishantnnb/spectrolipi
- Repository: https://github.com/nishantnnb/spectrolipi

## Overview

Spectrolipi is a browser-based bioacoustics tool for inspecting recordings, annotating spectrograms, managing recording and species metadata, editing audio, and exporting or sharing results. The main workflow runs from loading and visualizing sound through annotation and optional BirdNET assistance to clip or annotation export. README capabilities define several branches whose internal wiring is not visible in the supplied excerpts; those links are documented at the product level rather than inferred from imports. Processing is local in the browser, except for BirdNET model downloading and optional Xeno-canto API uploads.

Main entry points: [`birdnet_overlay.js`](https://github.com/nishantnnb/spectrolipi/blob/main/birdnet_overlay.js) (BirdNET assistance), [`spectrogram.js`](https://github.com/nishantnnb/spectrolipi/blob/main/spectrogram.js) (Spectrogram view), [`birdnet_v2.4.js`](https://github.com/nishantnnb/spectrolipi/blob/main/birdnet_v2.4.js) (BirdNET inference), [`filters.js`](https://github.com/nishantnnb/spectrolipi/blob/main/filters.js) (Audio filters and silence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_visualization["Sound visualization"]
  node_spectrogram["Spectrogram view<br/>[spectrogram.js]"]
  node_playback["Playback and navigation<br/>[playback.js]"]
  node_zoom["Zoom controls<br/>[zoom_controls.js]"]
  node_settings["Display settings"]
end

subgraph group_annotation["Annotation workflow"]
  node_create["Create annotations"]
  node_edit["Edit annotations"]
  node_delete["Delete annotations"]
  node_repeat["Repeat annotation"]
  node_stamp["Pattern templates<br/>[spectral_stamp.js]"]
  node_scc["Pattern detection<br/>[scc.js]"]
  node_birdnet["BirdNET assistance<br/>[birdnet_overlay.js]"]
  node_birdnet_runtime["BirdNET inference<br/>[birdnet_v2.4.js]"]
  node_model_files["BirdNET model files<br/>[birdnet_v2.4]"]
end

subgraph group_audio_tools["Audio tools"]
  node_audio_edit["Audio filters and silence<br/>[filters.js]"]
  node_normalize["Audio normalization<br/>[normalize.js]"]
end

subgraph group_metadata_species["Metadata and species"]
  node_metadata["Recording metadata<br/>[metadata.js]"]
  node_species["Species management<br/>[species_manage.js]"]
  node_recent_species["Recent species list<br/>[recent_species.js]"]
  node_local_storage[("Browser local storage")]
end

subgraph group_export_integrations["Export and integrations"]
  node_clips["Clip generation<br/>[generate_clips.js]"]
  node_annotation_export["Annotation import and export"]
  node_annotation_upload["Annotation upload"]
  node_xc["Xeno-canto integration<br/>[upload_xc.js]"]
  node_xc_service{{"Xeno-canto API"}}
end

node_researcher(("Researcher or birder"))

node_researcher -->|"loads and views"| node_spectrogram
node_spectrogram -->|"plays recording"| node_playback
node_researcher -->|"adjusts view"| node_zoom
node_researcher -->|"adjusts display"| node_settings
node_researcher -->|"draws annotations"| node_create
node_researcher -->|"edits annotations"| node_edit
node_researcher -->|"removes annotations"| node_delete
node_researcher -->|"repeats patterns"| node_repeat
node_researcher -->|"uses templates"| node_stamp
node_researcher -->|"runs detection"| node_scc
node_researcher -->|"requests analysis"| node_birdnet
node_birdnet -.->|"uses inference"| node_birdnet_runtime
node_birdnet_runtime -.->|"loads model"| node_model_files
node_birdnet -->|"inserts annotations"| node_create
node_researcher -->|"maintains metadata"| node_metadata
node_researcher -->|"manages species"| node_species
node_researcher -.->|"selects species"| node_recent_species
node_metadata -->|"backs up locally"| node_local_storage
node_species -->|"persists records"| node_local_storage
node_researcher -->|"edits sound"| node_audio_edit
node_audio_edit -->|"recomputes display"| node_spectrogram
node_researcher -->|"normalizes audio"| node_normalize
node_researcher -->|"exports clips"| node_clips
node_researcher -->|"imports or exports"| node_annotation_export
node_researcher -->|"uploads annotations"| node_annotation_upload
node_researcher -->|"shares annotation set"| node_xc
node_xc -->|"posts API upload"| node_xc_service

click node_spectrogram "https://github.com/nishantnnb/spectrolipi/blob/main/spectrogram.js"
click node_playback "https://github.com/nishantnnb/spectrolipi/blob/main/playback.js"
click node_zoom "https://github.com/nishantnnb/spectrolipi/blob/main/zoom_controls.js"
click node_settings "https://github.com/nishantnnb/spectrolipi/blob/main/spectrogram_settings.js"
click node_create "https://github.com/nishantnnb/spectrolipi/blob/main/create_annotations.js"
click node_edit "https://github.com/nishantnnb/spectrolipi/blob/main/edit_annotations.js"
click node_delete "https://github.com/nishantnnb/spectrolipi/blob/main/delete_annotations.js"
click node_repeat "https://github.com/nishantnnb/spectrolipi/blob/main/repeat_annotation.js"
click node_stamp "https://github.com/nishantnnb/spectrolipi/blob/main/spectral_stamp.js"
click node_scc "https://github.com/nishantnnb/spectrolipi/blob/main/scc.js"
click node_birdnet "https://github.com/nishantnnb/spectrolipi/blob/main/birdnet_overlay.js"
click node_birdnet_runtime "https://github.com/nishantnnb/spectrolipi/blob/main/birdnet_v2.4.js"
click node_model_files "https://github.com/nishantnnb/spectrolipi/tree/main/models/birdnet_v2.4"
click node_metadata "https://github.com/nishantnnb/spectrolipi/blob/main/metadata.js"
click node_species "https://github.com/nishantnnb/spectrolipi/blob/main/species_manage.js"
click node_recent_species "https://github.com/nishantnnb/spectrolipi/blob/main/recent_species.js"
click node_audio_edit "https://github.com/nishantnnb/spectrolipi/blob/main/filters.js"
click node_normalize "https://github.com/nishantnnb/spectrolipi/blob/main/normalize.js"
click node_clips "https://github.com/nishantnnb/spectrolipi/blob/main/generate_clips.js"
click node_annotation_export "https://github.com/nishantnnb/spectrolipi/blob/main/download_annotations.js"
click node_annotation_upload "https://github.com/nishantnnb/spectrolipi/blob/main/upload_annotations.js"
click node_xc "https://github.com/nishantnnb/spectrolipi/blob/main/upload_xc.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spectrogram,node_playback,node_zoom,node_settings toneBlue
class node_create,node_edit,node_delete,node_repeat,node_stamp,node_scc,node_birdnet,node_birdnet_runtime,node_model_files toneAmber
class node_audio_edit,node_normalize toneMint
class node_metadata,node_species,node_recent_species,node_local_storage toneRose
class node_clips,node_annotation_export,node_annotation_upload,node_xc,node_xc_service,node_researcher toneIndigo
```

## Components

### Sound visualization

- [Spectrogram view](https://github.com/nishantnnb/spectrolipi/blob/main/spectrogram.js): `spectrogram.js`
- [Playback and navigation](https://github.com/nishantnnb/spectrolipi/blob/main/playback.js): `playback.js`
- [Zoom controls](https://github.com/nishantnnb/spectrolipi/blob/main/zoom_controls.js): `zoom_controls.js`
- [Display settings](https://github.com/nishantnnb/spectrolipi/blob/main/spectrogram_settings.js): `spectrogram_settings.js`

### Annotation workflow

- [Create annotations](https://github.com/nishantnnb/spectrolipi/blob/main/create_annotations.js): `create_annotations.js`
- [Edit annotations](https://github.com/nishantnnb/spectrolipi/blob/main/edit_annotations.js): `edit_annotations.js`
- [Delete annotations](https://github.com/nishantnnb/spectrolipi/blob/main/delete_annotations.js): `delete_annotations.js`
- [Repeat annotation](https://github.com/nishantnnb/spectrolipi/blob/main/repeat_annotation.js): `repeat_annotation.js`
- [Pattern templates](https://github.com/nishantnnb/spectrolipi/blob/main/spectral_stamp.js): `spectral_stamp.js`
- [Pattern detection](https://github.com/nishantnnb/spectrolipi/blob/main/scc.js): `scc.js`
- [BirdNET assistance](https://github.com/nishantnnb/spectrolipi/blob/main/birdnet_overlay.js): `birdnet_overlay.js`
- [BirdNET inference](https://github.com/nishantnnb/spectrolipi/blob/main/birdnet_v2.4.js): `birdnet_v2.4.js`
- [BirdNET model files](https://github.com/nishantnnb/spectrolipi/tree/main/models/birdnet_v2.4): `models/birdnet_v2.4`

### Audio tools

- [Audio filters and silence](https://github.com/nishantnnb/spectrolipi/blob/main/filters.js): `filters.js`
- [Audio normalization](https://github.com/nishantnnb/spectrolipi/blob/main/normalize.js): `normalize.js`

### Metadata and species

- [Recording metadata](https://github.com/nishantnnb/spectrolipi/blob/main/metadata.js): `metadata.js`
- [Species management](https://github.com/nishantnnb/spectrolipi/blob/main/species_manage.js): `species_manage.js`
- [Recent species list](https://github.com/nishantnnb/spectrolipi/blob/main/recent_species.js): `recent_species.js`
- **Browser local storage**

### Export and integrations

- [Clip generation](https://github.com/nishantnnb/spectrolipi/blob/main/generate_clips.js): `generate_clips.js`
- [Annotation import and export](https://github.com/nishantnnb/spectrolipi/blob/main/download_annotations.js): `download_annotations.js`
- [Annotation upload](https://github.com/nishantnnb/spectrolipi/blob/main/upload_annotations.js): `upload_annotations.js`
- [Xeno-canto integration](https://github.com/nishantnnb/spectrolipi/blob/main/upload_xc.js): `upload_xc.js`
- **Xeno-canto API**

### Other components

- **Researcher or birder**

## Connections

- Researcher or birder → Spectrogram view: loads and views (evidence: `README.md`)
- Spectrogram view → Playback and navigation: plays recording (evidence: `README.md`)
- Researcher or birder → Zoom controls: adjusts view (evidence: `README.md`)
- Researcher or birder → Display settings: adjusts display (evidence: `README.md`)
- Researcher or birder → Create annotations: draws annotations (evidence: `README.md`)
- Researcher or birder → Edit annotations: edits annotations (evidence: `README.md`)
- Researcher or birder → Delete annotations: removes annotations (evidence: `README.md`)
- Researcher or birder → Repeat annotation: repeats patterns (evidence: `README.md`)
- Researcher or birder → Pattern templates: uses templates (evidence: `README.md`)
- Researcher or birder → Pattern detection: runs detection (evidence: `README.md`)
- Researcher or birder → BirdNET assistance: requests analysis (evidence: `README.md`)
- BirdNET assistance → BirdNET inference: uses inference
- BirdNET inference → BirdNET model files: loads model
- BirdNET assistance → Create annotations: inserts annotations (evidence: `birdnet_overlay.js`)
- Researcher or birder → Recording metadata: maintains metadata (evidence: `README.md`)
- Researcher or birder → Species management: manages species (evidence: `README.md`)
- Researcher or birder → Recent species list: selects species
- Recording metadata → Browser local storage: backs up locally (evidence: `metadata.js`)
- Species management → Browser local storage: persists records (evidence: `species_manage.js`)
- Researcher or birder → Audio filters and silence: edits sound (evidence: `README.md`)
- Audio filters and silence → Spectrogram view: recomputes display (evidence: `filters.js`)
- Researcher or birder → Audio normalization: normalizes audio (evidence: `README.md`)
- Researcher or birder → Clip generation: exports clips (evidence: `README.md`)
- Researcher or birder → Annotation import and export: imports or exports (evidence: `README.md`)
- Researcher or birder → Annotation upload: uploads annotations (evidence: `README.md`)
- Researcher or birder → Xeno-canto integration: shares annotation set (evidence: `README.md`)
- Xeno-canto integration → Xeno-canto API: posts API upload (evidence: `upload_xc.js`)