{"openapi":"3.1.0","info":{"title":"OpenLyryc Production API","version":"1.0.0","description":"Production-ready edge API endpoints for live synchronized lyric resolution, YouTube audio reference matching, and SoundCloud track streaming.","contact":{"name":"OpenLyryc Engineering","url":"https://openlyryc.pages.dev","email":"creator@openlyryc.dev"},"license":{"name":"MIT","url":"https://github.com/aurostron/openlyryc/blob/main/LICENSE"}},"servers":[{"url":"https://openlyryc.pages.dev","description":"Production Public Gateway"},{"url":"https://openlyryc-core.gamegata.workers.dev","description":"Direct Edge Worker"}],"tags":[{"name":"Lyrics","description":"Live synchronized lyric resolution with timestamped lines and word-level syllable tokens."},{"name":"Audio & Streams","description":"Real-time YouTube and SoundCloud audio candidate matching with duration alignment and negative keyword filtering."},{"name":"System","description":"Edge node health check and operational heartbeats."}],"paths":{"/api/v1/health":{"get":{"tags":["System"],"summary":"Edge Node Health Check","description":"Returns operational status, uptime timestamp, and active Cloudflare Edge Worker metadata.","operationId":"getHealth","responses":{"200":{"description":"Edge worker is operational and responding.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"service":{"type":"string","example":"OpenLyrics Cloudflare Edge Worker API"},"timestamp":{"type":"string","format":"date-time","example":"2026-10-15T09:30:00.000Z"}},"required":["status","service","timestamp"]}}}}}}},"/api/v1/youtube/search":{"get":{"tags":["Audio & Streams"],"summary":"Search & Rank YouTube Reference Audio","description":"Queries YouTube InnerTube API live with multi-factor ranking: duration proximity tie-breaking, official channel weighting, and negative keyword filtering (penalizing remixes, covers, and loops). Actively used in OpenLyryc Web Studio.","operationId":"searchYouTube","parameters":[{"name":"q","in":"query","required":true,"description":"Artist and title search query string.","schema":{"type":"string","example":"Otilia Bilionera"}},{"name":"duration","in":"query","required":false,"description":"Expected track duration in seconds for precision tie-breaking.","schema":{"type":"number","example":185}}],"responses":{"200":{"description":"Ranked candidate YouTube videos with calculated match scores.","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","example":"Otilia Bilionera"},"bestMatch":{"type":"object","nullable":true,"properties":{"videoId":{"type":"string","example":"v4xZUtTz0k4"},"title":{"type":"string","example":"Otilia - Bilionera (official video)"},"channelTitle":{"type":"string","example":"JHaps Records"},"durationSeconds":{"type":"number","example":185},"score":{"type":"number","example":98}}},"candidates":{"type":"array","items":{"type":"object","properties":{"videoId":{"type":"string","example":"v4xZUtTz0k4"},"title":{"type":"string","example":"Otilia - Bilionera (official video)"},"channelTitle":{"type":"string","example":"JHaps Records"},"durationSeconds":{"type":"number","example":185},"score":{"type":"number","example":98}}}}}}}}}}}},"/api/v1/soundcloud/search":{"get":{"tags":["Audio & Streams"],"summary":"Search & Resolve SoundCloud Audio Stream","description":"Searches SoundCloud live with token similarity matching and automatic acapella, cover, and karaoke penalization. Returns playback candidate URLs with matching scores.","operationId":"searchSoundCloud","parameters":[{"name":"q","in":"query","required":true,"description":"Track query string (title and artist).","schema":{"type":"string","example":"Otilia Bilionera Radio Edit"}}],"responses":{"200":{"description":"Ranked candidate SoundCloud tracks.","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","example":"Otilia Bilionera Radio Edit"},"bestMatch":{"type":"object","nullable":true,"properties":{"url":{"type":"string","example":"https://soundcloud.com/otilia-music/bilionera-radio-edit"},"title":{"type":"string","example":"Otilia - Bilionera (Radio Edit)"},"author":{"type":"string","example":"Otilia"},"score":{"type":"number","example":95}}},"candidates":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","example":"https://soundcloud.com/otilia-music/bilionera-radio-edit"},"title":{"type":"string","example":"Otilia - Bilionera (Radio Edit)"},"author":{"type":"string","example":"Otilia"},"score":{"type":"number","example":95}}}}}}}}}}}},"/api/v1/soundcloud/oembed":{"get":{"tags":["Audio & Streams"],"summary":"SoundCloud oEmbed & Artwork Proxy","description":"Proxies official SoundCloud oEmbed endpoints to fetch verified artwork thumbnails, track author, title, and HTML widget embed parameters without cross-origin friction.","operationId":"getSoundCloudOembed","parameters":[{"name":"url","in":"query","required":true,"description":"Full SoundCloud track URL.","schema":{"type":"string","example":"https://soundcloud.com/otilia-music/bilionera-radio-edit"}}],"responses":{"200":{"description":"SoundCloud oEmbed metadata object.","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"number","example":1},"type":{"type":"string","example":"rich"},"provider_name":{"type":"string","example":"SoundCloud"},"title":{"type":"string","example":"Otilia - Bilionera (Radio Edit)"},"author_name":{"type":"string","example":"Otilia"},"thumbnail_url":{"type":"string","example":"https://i1.sndcdn.com/artworks-example-t500x500.jpg"},"html":{"type":"string","example":"<iframe width=\"100%\" height=\"400\" ...></iframe>"}}}}}},"400":{"description":"Missing or invalid SoundCloud URL parameter."}}}},"/api/v1/lyrics":{"get":{"tags":["Lyrics"],"summary":"Resolve Live Synchronized Lyrics","description":"Resolves synchronized lyrics for any song via live upstream LRCLIB integration. Automatically parses line timestamps and converts syllable structures into the standard OpenLyrics schema.","operationId":"resolveLyrics","parameters":[{"name":"title","in":"query","required":true,"description":"Song title.","schema":{"type":"string","example":"Hello"}},{"name":"artist","in":"query","required":false,"description":"Artist or band name.","schema":{"type":"string","example":"Adele"}},{"name":"duration","in":"query","required":false,"description":"Track duration in seconds for fuzzy timing alignment.","schema":{"type":"number","example":295}},{"name":"format","in":"query","required":false,"description":"Response format: \"json\" (default OpenLyrics schema) or \"compact\" (delta-compressed representation).","schema":{"type":"string","enum":["json","compact"],"default":"json"}}],"responses":{"200":{"description":"Synchronized lyrics document resolved successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"$schema":{"type":"string","example":"https://openlyrics.dev/schema/v1.json"},"version":{"type":"number","example":1},"metadata":{"type":"object","properties":{"title":{"type":"string","example":"Hello"},"artist":{"type":"string","example":"Adele"},"album":{"type":"string","example":"25"},"duration":{"type":"number","example":295},"syncedBy":{"type":"string","example":"LRCLIB (via OpenLyryc Engine)"}}},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"line_1"},"text":{"type":"string","example":"Hello, it's me"},"start":{"type":"number","example":1.15},"end":{"type":"number","example":4.8}}}}}}}}},"404":{"description":"No synchronized lyrics found for the requested song query."}}}}}}