The Key to the Monolith
Accessing the Loracle API and initializing the music player widget requires a valid license token.
API Token Verification Flow:
- The embedded script sends the API Key to `/v1/embed/token` during widget initialization.
- The backend verifies the request's Origin (or Referer) header. The website must match your registered Allowed Domains.
- If valid, a short-lived JWT token (1-hour expiry) is returned to the browser.
- The player uses this JWT token to authenticate and fetch widget parameters.
Where does the music come from?
We don't host music files (MP3) on our servers and waste your bandwidth. Loracle offers two distinct client-focused data models to load files:
- Local Browser Storage (IndexedDB):: Tracks are stored directly in the visitor's browser cache. Songs persist across page reloads with zero network bandwidth.
- External Audio Links (API Tracks):: A list of track metadata (Title, Artist, External MP3 URL) is stored on our database. The widget fetches this metadata via API on startup.
Note: The data returned from the API consists strictly of lightweight text metadata. Your network bandwidth is never bloated.
Embeddable Player Setup
Integrating the Loracle music player into your project is extremely simple. Just create a container element, and include the script integration tag near the end of your page.
Input Parameters Details:
| Attribute | Type | Description |
|---|---|---|
| data-api-key | String | Your Workspace license key (e.g. th_live_...). |
| data-embed-token | String | Gelişmiş güvenlik ve sıfır API anahtarı ifşası için sunucu tarafında üretilen kısa ömürlü JWT. |
| data-theme | light | dark | auto | Initial UI theme theme (light or dark). |
| data-container-id | String | The mounting element HTML id. If omitted, the widget initializes in floating mode. |
🔐 Sunucu Taraflı Güvenli Token İmzalama (Signed Token Flow)
API anahtarınızı doğrudan istemci HTML kodunda (data-api-key) ifşa etmek istemiyorsanız, sunucu tarafında bir endpoint oluşturarak kısa ömürlü (1 saatlik) JWT talep edebilir ve widget'ı data-embed-token özniteliği ile başlatabilirsiniz.
Üretilen bu JWT tokenlar, backend sunucumuz tarafından asimetrik RS256 algoritmasıyla doğrulanır.
📦 Modern Framework Sarmalayıcıları (SDK Wrappers)
Düz script tag yerine, React veya Vue projelerinizde Loracle oynatıcısını yerel bir bileşen olarak kolayca monte edip kullanabilirsiniz.
Quotas and Limits Control
Loracle enforces plan-based quota control to protect database loading and track illegitimate player distributions.
| Feature / Limit | Free Plan | Pulse Plan |
|---|---|---|
| Maximum Songs (Tracks Limit) | 10 Tracks | 25 Tracks |
| Domain Restrictions Limit | 1 Domain | 10 Domains |
| Monthly Request Quota (API Hits) | 5,000 requests | 250,000 requests |
| Rate Limiting (Throttle) | 60 req / min | 300 req / min |
What Happens When Quotas are Exceeded?
- If monthly limits are hit or an unauthorized domain is detected, the API returns a 402 Payment Required or 403 Forbidden status.
- The music player UI locks and displays a lock icon 🔒 with "License Verification Failed".
- On session expirations, local IndexedDB tracks might still play, but API metadata lookups and lyrics matching services are suspended.
Built on tahost.cloud
Loracle is built on tahost.cloud's paper-thin edge network architecture. Verification telemetry requests are processed instantly by the nearest node, ensuring zero negative impact on your page Load times (LCP).
GLOBAL LATENCY SPECTRUM: 0.002ms - 14ms · UNBLEACHED SILICON INFRASTRUCTURE