Bioacoustic workbench: isolate elephant WAV recordings from mechanical noise in the browser (spectrograms, playback, export). Backend: FastAPI, STFT / HPSS-style DSP, SciPy stack. Optional: Google Gemini for short noise explanations. License: MIT.

• Overview
• Screenshots
• Prerequisites
• Quick start
• Deploy backend (Render)
• Deploy frontend (Vercel)
• Configuration
• Usage
• System architecture
• API reference
• Repository structure
• Batch CLI
• DSP notes
• Troubleshooting
• License

Field recordings mix infrasonic elephant rumbles with engines, wind, and gear. EleSynth lets researchers clean one file or many segments, compare before/after visually and audibly, and download cleaned WAV output.

Landing (home): value proposition and entry to analysis.

Marketing carousel: before/after spectrogram comparison (“See it”).

Bioacoustics Lab (/workbench): intake, session queue, and empty analysis canvas before files are processed.

Use two terminals from the repo root.

1. Create and enter the venv, install deps, run the API:

   cd backend
   python -m venv .venv

2. Activate (current directory must be backend/):

   OS	Command
   Windows	.venv\Scripts\activate
   macOS / Linux	source .venv/bin/activate

3. Install and start:

   pip install -r requirements.txt
   uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

4. Check health: http://127.0.0.1:8000/api/health → {"status":"ok"}.

1. Install and configure:

   cd frontend
   npm install

2. Env file (frontend/.env.local):

   OS	Command
   macOS / Linux	cp .env.example .env.local
   Windows	copy .env.example .env.local

   Required:

   NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8000

3. Dev server:

   npm run dev

4. Open http://localhost:3000 → Begin Analysis or /workbench → upload WAV → process → compare → download.

cd frontend
npm run build
npm run start

Set NEXT_PUBLIC_API_BASE_URL to your deployed API (no trailing slash).

The FastAPI app in backend/ is a good fit for a Render Web Service. The repo includes a Blueprint at render.yaml (Python Starter in oregon, rootDir: backend).

1. In the Render dashboard: New → Blueprint, connect this repository, apply render.yaml.
2. When prompted, set FRONTEND_ORIGIN to your deployed frontend origin(s), comma-separated, no trailing slash (for example https://your-app.vercel.app). This extends the CORS allowlist in backend/app/main.py.
3. Optionally set GEMINI_API_KEY or GOOGLE_API_KEY for Gemini; omit if you only need DSP.
4. After deploy, confirm GET https://<your-service>.onrender.com/api/health.
5. On Vercel (or any Next host), set NEXT_PUBLIC_API_BASE_URL to that same API origin (no trailing slash).

Without a Blueprint: create a Web Service, set Root Directory to backend, build pip install -r requirements.txt, start uvicorn app.main:app --host 0.0.0.0 --port $PORT, health check path /api/health. Python version follows backend/runtime.txt (3.11.x).

SciPy and Librosa are memory-heavy; if the build or runtime fails with OOM, upgrade the instance type in Render. Very large upload bodies may hit platform limits; see Render request limits.

The Next.js app lives under frontend/. Vercel should build that directory only (the backend stays on Render).

1. Import this GitHub repository in the Vercel dashboard (Add New → Project).

2. Root Directory: set to frontend (monorepo). Framework preset should detect Next.js.

3. Node.js: use 20.x (matches local dev).

4. Environment variables (Production, and Preview if you use them):

   Name	Value
   NEXT_PUBLIC_API_BASE_URL	Your Render API origin, e.g. https://elesynth-api.onrender.com (no trailing slash)

   Optional: set NEXT_PUBLIC_DIRECT_API_BASE_URL to the same URL if you rely on the fallback path in frontend/lib/api.ts.

5. Deploy. Your site will be at https://<project>.vercel.app (or your custom domain).

6. CORS: On Render, set FRONTEND_ORIGIN to that exact origin (comma-separated if you have several, e.g. production + a preview URL). Redeploy the API if you change it. The app already allows localhost:3000 by default in backend/app/main.py.

Preview deployments: each preview has its own *.vercel.app URL. Add each origin you need to FRONTEND_ORIGIN on Render, or test previews only against an API that allows those origins.

Uploads: Audio is sent from the browser directly to the Render API, not through Vercel’s serverless layer, so the Next app itself does not need a larger body limit for POST /api/process-audio.

Loaded in backend/app/main.py from backend/.env and repo root .env (order is defined in code).

Gemini responses are cached under backend/.cache/gemini_results.json (per file digest). Quota errors trigger a short API backoff.

(app) is a Next.js route group: shared app/(app)/layout.tsx (shell, session); the folder name is not part of the URL.

Columns: filename, start_time, end_time (seconds), aligned with staged files.

POST /api/process-audio accepts .wav only.

1. Client: multipart/form-data with file. Shipped UI (frontend/lib/api.ts) sends file only; server still accepts optional metadata_json.
2. Parse: load_audio_from_bytes → optional ProcessMetadata → windows_from_metadata. No metadata = one window from 0 to full duration.
3. Process: process_clip in dsp.py (rumble band 10 Hz to 1000 Hz in code). Merge clips with gaps → build_spectrogram_preview → JSON + base64 WAV (ProcessAudioResponse, frontend/lib/types.ts).
4. Gemini (optional): noise_analysis, research_metadata; cached by content hash.

Returns JSON for connectivity checks.

Content-Type: multipart/form-data

Response: original_filename, cleaned_filename, sample_rate, duration_seconds, processed_windows, cleaned_audio_base64, before_spectrogram, after_spectrogram (times, frequencies, magnitude_db), noise_analysis, research_metadata.

AAAM/
├── docs/
│   └── images/                  # README screenshots
├── render.yaml                  # Render Blueprint (FastAPI web service)
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI, CORS, routes, Gemini, cache
│   │   ├── dsp.py               # WAV I/O, process_clip, spectrograms
│   │   └── schemas.py           # Pydantic models
│   ├── requirements.txt
│   ├── runtime.txt              # Python version for Render (and similar hosts)
│   └── .env                     # optional (or use repo root .env)
├── frontend/
│   ├── app/
│   │   ├── layout.tsx           # root layout, fonts, providers
│   │   ├── page.tsx             # marketing home
│   │   ├── globals.css
│   │   └── (app)/               # route group (omitted from URL)
│   │       ├── layout.tsx       # app shell for /upload, /workbench
│   │       ├── upload/page.tsx
│   │       └── workbench/page.tsx
│   ├── components/              # layout/, marketing/, workbench, ui/
│   ├── lib/
│   │   ├── api.ts
│   │   └── types.ts
│   ├── public/
│   ├── package.json
│   └── .env.local               # from .env.example (gitignored)
├── isolate_elephant_vocalizations.py
├── _archive/Elephant/           # legacy reference only
├── LICENSE
└── README.md

From repo root, same Python env as backend:

python isolate_elephant_vocalizations.py --audio-dir PATH_TO_WAVS --annotations PATH_TO_CSV --output-dir cleaned_audio

CSV: filename, start_time, end_time.

Low fundamentals (~10-20 Hz) with margin, harmonics to ~1000 Hz, harmonic-percussive separation and band masking, inverse STFT to WAV.

MIT License.