If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/cgzirim/seek-tune shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 6mo ago

• Last commit 6mo ago
• 3 active contributors
• MIT licensed
• Tests present
• ⚠ Slowing — last commit 6mo ago
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 90% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live cgzirim/seek-tune repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/cgzirim/seek-tune.

What it runs against: a local clone of cgzirim/seek-tune — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in cgzirim/seek-tune | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 199 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of cgzirim/seek-tune. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/cgzirim/seek-tune.git
#   cd seek-tune
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of cgzirim/seek-tune and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "cgzirim/seek-tune(\\.git)?\\b" \\
  && ok "origin remote is cgzirim/seek-tune" \\
  || miss "origin remote is not cgzirim/seek-tune (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 199 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~169d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/cgzirim/seek-tune"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

SeekTune is a Go + React implementation of Shazam's audio fingerprinting algorithm that identifies songs from short audio samples. It chains Spotify API lookups with YouTube downloads to provide a complete song recognition and retrieval pipeline, using FFT-based spectral analysis and constellation mapping to match unknown audio against a local database. Monorepo with server/ (Go backend using FFT/spectrogram analysis in server/shazam/, MongoDB/SQLite in server/db/) and client/ (React SPA with WASM fingerprinting via fingerprint.wasm in public/). Backend exposes REST/WebSocket via main.go and cmdHandlers.go; frontend components in client/src/components/ handle recording, matching UI, and YouTube integration via react-youtube.

Music app developers and audio processing engineers who want to add song recognition capabilities without licensing Shazam directly; also useful for researchers studying audio fingerprinting algorithms and developers needing to bulk-download songs matched to Spotify metadata.

Active hobby/learning project with complete feature set (fingerprinting, API integration, Docker deployment) but limited test coverage and no visible CI/CD pipeline. Single maintainer (@cgzirim), no release tags visible, and no indication of production usage at scale. Verdict: proof-of-concept quality, suitable for learning but requires hardening before production use.

Moderate risk: heavy dependency on external APIs (Spotify, YouTube via yt-dlp) with no fallback strategy; WASM fingerprint module in client could have browser compatibility issues; Go dependencies managed but not pinned to specific versions in go.mod. YouTube/yt-dlp scraping may break if APIs change. Single maintainer means security vulnerabilities could go unpatched.

No visible commit history or PR board in provided data, but project structure suggests recent completion of core features: WASM build pipeline for client fingerprinting (fingerprint.wasm), Docker multi-container setup (docker-compose.yml), and dual-database support (SQLite for dev, MongoDB for prod). No active branch/milestone information available.

git clone https://github.com/cgzirim/seek-tune.git && cd seek-tune && echo 'SPOTIFY_CLIENT_ID=xxx SPOTIFY_CLIENT_SECRET=yyy' > server/.env && docker-compose up --build, then visit http://localhost:8080. Or natively: cd server && go get ./... && go run *.go serve & cd client && npm install && npm start.

Daily commands: Backend: cd server && go run *.go serve [-proto http|https] [-port 5000]. Frontend: cd client && npm start (runs on :3000 via react-scripts). Or unified: docker-compose up --build from root (serves on :8080). Download songs: go run *.go download <spotify-url>. Batch save: go run *.go save [-f|--force] <path>.

• server/shazam/fingerprint.go: Core Shazam algorithm: generates audio constellation maps from spectrogram peaks for fingerprint matching
• server/shazam/spectrogram.go: Transforms raw audio into STFT matrix required for peak detection and fingerprint generation
• server/shazam/fft.go: FFT implementation (likely wrapping cgo or existing library) converting time-domain audio to frequency domain
• server/db/mongo.go: MongoDB fingerprint database interface; primary storage for indexed fingerprints and song metadata
• server/main.go: Server entry point; defines HTTP routes and orchestrates Spotify/YouTube integration with fingerprinting pipeline
• client/public/fingerprint.wasm: Compiled WASM binary running fingerprinting client-side before uploading to backend; critical for browser audio processing
• client/src/components/Listen.js: Primary UI component: orchestrates MediaRecorder, audio encoding via FFmpeg.js, and real-time match display
• server/cmdHandlers.go: CLI command handlers for download (Spotify->YouTube), save (bulk local audio ingestion), and serve (HTTP server startup)

Add Shazam algorithm improvements: edit server/shazam/{fft.go, fingerprint.go, spectrogram.go}. Expand database support: add driver in server/db/ mirroring mongo.go/sqlite.go structure. Modify UI: React components in client/src/components/{Form.js, Listen.js, CarouselSliders.js}. Rebuild WASM: wasm_exec.go toolchain (Go 1.11+) outputs to client/public/fingerprint.wasm. API routes: defined in main.go and cmdHandlers.go.

1. Spotify API requires fresh oauth tokens; .env vars SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET mandatory (README implies auto-caching but failure mode unclear). 2. YT-DLP must be on $PATH; no bundled version, scraping may break if YouTube layout changes. 3. WASM fingerprint module requires Go 1.11+; wasm_exec.js loader may mismatch Go version output. 4. FFmpeg.js in client has async initialization; race conditions possible if recording starts before library loads. 5. MongoDB connection string not shown in .env.example; SQLite fallback exists but schema compatibility untested. 6. Socket.IO v2.5.0 is outdated (current: 4.x); potential security implications. 7. Docker assumes FFmpeg, yt-dlp, and ffmpeg-python available in image (Dockerfile not shown; may fail silently).

• Constellation Map (Audio Fingerprinting) — Core technique used in server/shazam/fingerprint.go—maps spectrogram peaks to (frequency, time) anchors for robust, rotation-invariant song matching despite audio degradation
• Short-Time Fourier Transform (STFT) — server/shazam/spectrogram.go uses STFT to convert audio into time-frequency matrix; essential for peak detection in fingerprinting
• FFT (Fast Fourier Transform) — Underlying algorithm in server/shazam/fft.go that powers spectrogram generation from raw audio samples
• WebAssembly (WASM) — client/public/fingerprint.wasm enables client-side fingerprint generation without backend round-trip; compiled from Go via go tool wasm
• OAuth 2.0 Client Credentials Flow — Used in server/main.go to authenticate with Spotify API for song metadata and download links without user login
• Hash-Based Indexing for Fingerprints — server/db/ likely uses hash tables or indexed B-trees to match unknown fingerprints against database in milliseconds (exact indexing strategy not visible but critical for performance)
• Media Recorder API & WAV Encoding — client/src uses ExtendableMediaRecorder + wav-encoder to capture browser audio in lossless WAV before fingerprinting; critical for preserving audio fidelity for matching

• spotify/basic-spotify-authenticator — Reference implementation for Spotify OAuth flow that SeekTune uses for API access
• yt-dlp/yt-dlp — Underlying YouTube download tool hardcoded as external dependency; breaks if API changes
• go-audio/audio — Go audio processing library that could replace or augment SeekTune's FFT/spectrogram pipeline
• chromaprint/chromaprint — Alternative audio fingerprinting library (C++) that SeekTune's Shazam implementation competes with
• dejavu-music-recognition/dejavu — Python-based Shazam clone using similar FFT + constellation approach; useful for algorithm comparison

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for server/shazam package (fingerprint, FFT, spectrogram algorithms)

The core Shazam algorithm implementation in server/shazam/ (fft.go, fingerprint.go, spectrogram.go, shazam.go) has no visible test files. These are mathematically complex signal processing functions that are critical to the song recognition accuracy. Adding comprehensive unit tests would catch regressions, document expected behavior, and increase maintainability for contributors working on the algorithm.

• [ ] Create server/shazam/fft_test.go with tests for FFT transform correctness
• [ ] Create server/shazam/spectrogram_test.go with tests for spectrogram generation from audio samples
• [ ] Create server/shazam/fingerprint_test.go with tests for hash generation and constellation map creation
• [ ] Create server/shazam/shazam_test.go with integration tests matching sample audio against known fingerprints
• [ ] Add test fixtures (sample .wav files) in server/shazam/testdata/

Add GitHub Actions CI pipeline for server (Go) and client (React) with multi-stage builds

The repo has appspec.yml and shell scripts (scripts/before_install.sh, scripts/start_server.sh) suggesting manual/CodeDeploy deployments, but no GitHub Actions workflow. A proper CI pipeline would catch build failures, linting issues, and dependency vulnerabilities before merge. This is especially important given the server uses FFmpeg (external dependency) and the client uses WASM (wasm/build.sh).

• [ ] Create .github/workflows/server-ci.yml to run go build, go test, and go vet on server/
• [ ] Create .github/workflows/client-ci.yml to run npm install, npm run build, and npm test on client/
• [ ] Add docker build step in workflows to verify Dockerfile builds successfully
• [ ] Add .github/workflows/wasm-ci.yml to verify wasm/build.sh completes without errors
• [ ] Configure branch protection rules to require all workflows to pass before merge

Add integration tests and documentation for server/spotify and server/wav packages

The server/spotify/ package (spotify.go, downloader.go, youtube.go) and server/wav/ package (wav.go, convert.go) handle critical external integrations and audio format conversion but lack test coverage. The README mentions Spotify/YouTube integration but provides no developer documentation on how these packages work. Adding tests and an API documentation file would help contributors understand the data flow and add features (e.g., support for other audio sources or formats).

• [ ] Create server/spotify/spotify_test.go with mocked API tests for token refresh, search, and playlist operations
• [ ] Create server/wav/convert_test.go with tests for audio format conversion using sample audio files
• [ ] Create server/INTEGRATION.md documenting the Spotify OAuth flow, YouTube downloader setup, and WAV conversion pipeline
• [ ] Add mock fixtures in server/testdata/ for Spotify API responses
• [ ] Document required environment variables (Spotify CLIENT_ID, CLIENT_SECRET, YouTube API key) in server/.env.example with descriptions

• Add unit tests for server/shazam/fingerprint.go constellation matching logic—currently no test files visible, critical for bug confidence
• Document the WASM build pipeline: create Makefile target and CI step to rebuild fingerprint.wasm from Go source; currently opaque how changes to Go code propagate to browser
• Implement graceful fallback in client/src/components/Listen.js if FFmpeg.js fails to load; currently will hang on recording attempt with no user feedback

• High · Outdated socket.io-client Dependency — client/package.json - dependencies. The package.json uses socket.io-client version ^2.5.0, which is significantly outdated (released in 2020). This version contains known security vulnerabilities including potential XSS and DoS vulnerabilities. Current stable version is 4.x. Fix: Update socket.io-client to the latest stable version (^4.7.0 or higher). Run 'npm audit fix' to address known vulnerabilities.
• High · Unverified External Binary Installation in Docker — Dockerfile - pip install yt-dlp. The Dockerfile installs yt-dlp via pip with the --break-system-packages flag in a production container. This bypasses safety constraints and yt-dlp is a third-party tool that downloads from external sources without verification, creating supply chain and code execution risks. Fix: Use a separate stage for yt-dlp or verify package integrity. Consider using security scanning (pip-audit) and pinning exact versions. Remove --break-system-packages flag and use proper venv isolation.
• High · Sensitive Environment Variables Exposed in docker-compose.yml — docker-compose.yml - environment section. Database credentials (DB_USER, DB_PASSWORD), Spotify API secrets (SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET), and backend URLs are defined as plain-text environment variables in docker-compose.yml. These can be exposed in logs, process listings, and version control if .env files are committed. Fix: Use Docker secrets or a secrets management tool (HashiCorp Vault, AWS Secrets Manager). Never commit .env files. Use .env.example with placeholder values only. Implement runtime secret injection.
• Medium · Missing Security Headers Configuration — server/main.go (inferred) - static file serving. The React frontend is served from a Go backend (static files in /static), but there is no visible configuration for security headers (Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security). This increases XSS and clickjacking attack surface. Fix: Implement security headers middleware in the Go server. Add CSP policies, set X-Frame-Options: DENY, X-Content-Type-Options: nosniff, and HSTS headers. Use established Go middleware like secure package.
• Medium · Potential SQL Injection via Database Abstraction — server/db/sqlite.go, server/cmdHandlers.go, server/socketHandlers.go. The codebase includes both SQLite (server/db/sqlite.go) and MongoDB (server/db/mongo.go) support. Without visible ORM usage or parameterized query patterns, there's risk of SQL injection if raw queries are constructed with user input, especially in cmdHandlers.go or socketHandlers.go. Fix: Use parameterized queries/prepared statements exclusively. Implement input validation and sanitization. Consider using an ORM (GORM, sqlc) for type-safe database operations. Audit cmdHandlers.go and socketHandlers.go for dynamic query construction.
• Medium · No CORS Configuration Visible — server/main.go (inferred) - HTTP server setup. The application accepts connections from both WebSocket (socket.io-client) and HTTP clients. Without visible CORS policy configuration in the Go server, the API may be vulnerable to cross-origin attacks or overly permissive cross-origin access. Fix: Implement strict CORS policies. Whitelist specific origins, restrict HTTP methods, and validate request headers. Use a CORS middleware in Go (e.g., github.com/rs/cors). Set appropriate Access-Control headers.
• Medium · Outdated Alpine Base Image with Known Vulnerabilities — Dockerfile - final stage base image. The Dockerfile uses 'FROM alpine:latest' without pinning a specific version. The latest Alpine tag can change, introducing unpredictable vulnerabilities. Additionally, no image scanning is performed in the build pipeline. Fix: Pin Alpine to a specific version (e.g., alpine:3.20). Implement container image scanning in CI/CD (Trivy, Grype). Use multi-stage builds (already done) to minimize final image size and attack surface.
• Medium · — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.