api.airtune.ai — Radio Unified API

Real-world project built and operated entirely through MeshPOP's 5-layer stack.

Live: api.airtune.ai — 41,000+ stations, 201 countries, multilingual search

What It Does

Unified radio station API that aggregates stations from multiple sources (RadioBrowser, Icecast, auto-broadcasters) into a single searchable database. Features multilingual search (Korean, Japanese, Chinese, Russian, and more), geo-location, AI recommendations, and real-time now-playing tracking.

The 5 Layers in Action

┌─────────────────────────────────────────────────┐
│  Layer 5 — Vault (Secrets)                      │
│  API keys for external radio sources             │
│  pip install sv-vault                            │
├─────────────────────────────────────────────────┤
│  Layer 4 — MeshDB (Search)                      │
│  Search API source code, find endpoints          │
│  pip install meshpop-db                          │
├─────────────────────────────────────────────────┤
│  Layer 3 — mpop (Control Plane)                 │
│  Monitor health, restart, check logs, diagnose   │
│  pip install meshpop                             │
├─────────────────────────────────────────────────┤
│  Layer 2 — vssh (Transport)                     │
│  Deploy code to v4, transfer DB snapshots        │
│  pip install vssh                                │
├─────────────────────────────────────────────────┤
│  Layer 1 — Wire (Network)                       │
│  Encrypted mesh tunnel: v4 ↔ v1 (nginx proxy)   │
│  pip install meshpop-wire                        │
└─────────────────────────────────────────────────┘

Infrastructure

Component	Server	Details
API Server	v4	Python http.server, port 8092
Reverse Proxy	v1	nginx → v4 via Wire VPN
Main DB	v4	`radio_unified.db` (728MB, SQLite)
Playlog DB	v4	`radio_playlog.db` (634MB, SQLite)
Stations DB	v4	`radio_stations.db` (29MB, SQLite)
Source	v4	`/home/radio/radio_api_v4.py` (54KB)

API Endpoints

Core

Endpoint	Description
`GET /health`	Health check — station counts, timestamp
`GET /stats`	Full statistics — sources, countries, languages
`GET /search?q=jazz&limit=20`	Full-text search with multilingual support
`GET /station/{id}`	Get station by ID
`POST /submit`	Submit a new station

Station Listings

Endpoint	Description
`/stations`	All stations (paginated)
`/stations/bylanguage/{lang}`	Filter by language
`/stations/byname/{name}`	Filter by name
`/stations/bycountry/{country}`	Filter by country
`/stations/bycountrycode/{code}`	Filter by country code
`/stations/bytag/{tag}`	Filter by tag/genre
`/stations/bycodec/{codec}`	Filter by codec
`/stations/random`	Random stations
`/stations/topvote`	Top voted
`/stations/recent`	Recently added
`/stations/trending`	Currently trending
`/stations/nearby?lat=&lng=`	Geo-location based
`/stations/tastemakers`	Influential stations

Recommendations

Endpoint	Description
`/recommend`	AI-powered recommendations
`/recommend/genre/{genre}`	By genre
`/recommend/hq`	High quality only
`/recommend/popular`	Most popular
`/recommend/voted`	Highest voted
`/recommend/live`	Currently live
`/recommend/country`	By user's country

Analytics

Endpoint	Description
`/nowplaying`	Currently playing tracks
`/trending`	Trending tracks
`/songs/breakout`	Breakout songs
`/songs/global`	Global chart
`/songs/cooccurrence`	Co-occurrence analysis
`/stats/hourly`	Hourly statistics

Metadata

Endpoint	Description
`/languages`	All languages
`/countries`	All 201 countries
`/tags`	All tags/genres
`/codecs`	All audio codecs

Try It

# Health check
curl https://api.airtune.ai/health

# Search for jazz stations
curl "https://api.airtune.ai/search?q=jazz&limit=5"

# Korean search (multilingual)
curl "https://api.airtune.ai/search?q=재즈&limit=5"

# Random stations
curl https://api.airtune.ai/stations/random

# High quality recommendations
curl https://api.airtune.ai/recommend/hq

AI Development Loop

Airtune is developed using the MeshPOP AI loop — Claude writes code, deploys it, runs it, reads the logs, and fixes it:

1. Write Code

Claude writes API endpoints, using meshdb_search to find existing code patterns.

2. Deploy

# Transfer updated code via vssh (L2)
vssh put radio_api_v4.py v4:/home/radio/radio_api_v4.py

# Restart service via mpop (L3)
mpop exec "systemctl restart radio-api" --server v4

3. Verify

# Health check
mpop exec "curl -s localhost:8092/health" --server v4

# Test search
mpop exec "curl -s 'localhost:8092/search?q=jazz&limit=3'" --server v4

4. Monitor

# Check logs
mpop logs v4 --service radio-api --tail 50

# Continuous monitoring
mpop watch --check "curl -s localhost:8092/health"

5. Fix

If something breaks, AI reads logs, searches code via MeshDB (L4), writes a fix, and re-deploys — without human intervention.

CI/CD Script

The airtune-cicd.sh script automates the complete loop:

./airtune-cicd.sh loop     # Full: deploy → verify → fix → repeat
./airtune-cicd.sh deploy   # Deploy latest code
./airtune-cicd.sh verify   # Health + endpoint tests
./airtune-cicd.sh logs 50  # View recent logs
./airtune-cicd.sh status   # Service status

Features

Multilingual search — Korean, Japanese, Chinese, French, German, Spanish, Russian, etc.
Rate limiting — 100 req/min per IP
CORS enabled — Works from any frontend
PLS resolution — Auto-resolves Shoutcast playlist URLs
TTL caching — 5-minute cache for metadata
Geo-location — Find stations near coordinates

The point of Airtune is not the radio API itself — it's proof that AI can build, deploy, and operate real production services using MeshPOP as its infrastructure layer. You can do this too.