Developer Guide — Echo Music Lossless

Quick Start

How It Works

The Echo Music Lossless database is a single JSON file hosted on GitHub. It maps song + artist pairs to FLAC audio URLs. You fetch the JSON, match songs by name, and stream the corresponding audio.

1 Fetch music.json

2 Match song + artist

3 Play lossless track

API Reference

Canvas Database URL

The primary endpoint to fetch the complete canvas database:

ENDPOINT

https://lossless.echomusic.fun/music.json

This URL always serves the latest version from the main branch. Cache it on your server for performance.

Response Schema

The JSON file follows this structure:

JSON

{
  "items": [
    {
      "song": "Blinding Lights",
      "artist": "The Weeknd",
      "url": "https://lossless.echomusic.fun/Music/blinding_lights.flac"
    }
  ]
}

Field	Type	Description
`items`	Array	The list of all canvas entries
`items[].song`	String	The song title (case-sensitive as contributed)
`items[].artist`	String	The artist or band name
`items[].url`	String	Direct URL to the audio file (`.flac`)

Integration Examples

JavaScript / Web

Fetch the database and find a canvas for a playing song:

JavaScript

const DATABASE_URL = 'https://lossless.echomusic.fun/music.json';

// Fetch and cache the canvas database
async function loadDB() {
  const res = await fetch(DATABASE_URL);
  const data = await res.json();
  return data.items || [];
}

// Find a canvas for a given song + artist
function findTrack(items, songTitle, artistName) {
  const query = `${songTitle} ${artistName}`.toLowerCase();
  return items.find(item => {
    const entry = `${item.song} ${item.artist}`.toLowerCase();
    return entry === query;
  });
}

// Usage
const db = await loadDB();
const match = findTrack(db, 'Blinding Lights', 'The Weeknd');

if (match) {
  const audio = document.getElementById('audio-player');
  audio.src = match.url;
  audio.play();
}

HTML Video Player

A minimal HTML structure to render a canvas behind your music player:

HTML

<div class="player-container" style="position: relative;">
  <audio id="audio-player" controls style="width: 100%;"></audio>

  <!-- Your player UI goes on top -->
  <div style="position: relative; z-index: 1;">
    <h2 id="song-title">Blinding Lights</h2>
    <p id="artist-name">The Weeknd</p>
    <!-- playback controls, progress bar, etc. -->
  </div>
</div>

Android / Kotlin

Use ExoPlayer to play canvas videos in your Android app:

Kotlin

// 1. Add ExoPlayer dependency in build.gradle
// implementation("androidx.media3:media3-exoplayer:1.3.0")
// implementation("androidx.media3:media3-ui:1.3.0")

// 2. Fetch music.json (using OkHttp / Retrofit)
suspend fun fetchDB(): List<TrackEntry> {
    val response = httpClient.get(DATABASE_JSON_URL)
    val json = JSONObject(response.body.string())
    val items = json.getJSONArray("items")
    return (0 until items.length()).map { i ->
        val obj = items.getJSONObject(i)
        TrackEntry(
            song = obj.getString("song"),
            artist = obj.getString("artist"),
            url = obj.getString("url")
        )
    }
}

// 3. Play the audio
fun playAudio(url: String, playerView: PlayerView) {
    val player = ExoPlayer.Builder(context).build()
    playerView.player = player

    val mediaItem = MediaItem.fromUri(url)
    player.setMediaItem(mediaItem)
    player.prepare()
    player.play()
}

iOS / Swift

Use AVPlayer to play canvas videos in your iOS app:

Swift

import AVKit

struct TrackEntry: Codable {
    let song: String
    let artist: String
    let url: String
}

struct TrackDB: Codable {
    let items: [TrackEntry]
}

// Fetch the database
func loadDB() async throws -> [TrackEntry] {
    let url = URL(string: "https://lossless.echomusic.fun/music.json")!
    let (data, _) = try await URLSession.shared.data(from: url)
    let db = try JSONDecoder().decode(TrackDB.self, from: data)
    return db.items
}

// Play audio
func playAudio(urlString: String) {
    guard let url = URL(string: urlString) else { return }
    let player = AVPlayer(url: url)
    player.play()

    player.play()
}

Python (Backend / Bot)

Useful for Discord bots, Telegram bots, or backend services:

Python

import requests

CANVAS_URL = "https://lossless.echomusic.fun/music.json"

def load_db():
    """Fetch the full track database."""
    response = requests.get(CANVAS_URL)
    response.raise_for_status()
    return response.json().get("items", [])

def find_canvas(items, song_title, artist_name):
    """Find a matching canvas entry."""
    query = f"{song_title} {artist_name}".lower()
    for item in items:
        entry = f"{item['song']} {item['artist']}".lower()
        if entry == query:
            return item
    return None

# Example usage
db = load_db()
track = find_canvas(db, "Starboy (feat. Daft Punk)", "The Weeknd")
if track:
    print(f"Track URL: {track['url']}")

Best Practices

Cache the Database

Don't fetch music.json on every song change. Load it once on startup and cache it locally. Refresh periodically (e.g., every 30 minutes) to pick up new community contributions.

Fuzzy Matching

Song titles may not match exactly due to special characters, casing, or feat. tags. Use case-insensitive matching and strip common suffixes like (feat. …) for better hit rates.

Support FLAC

Track URLs are .flac. On web, most modern browsers support it natively. For mobile, AVPlayer and ExoPlayer both support FLAC.

High Fidelity

Always ensure users are on a good connection when streaming lossless files, or offer a way to download them offline to save bandwidth.

Usage & Attribution

License & Fair Use

Open Source

The canvas database is GPL-3.0 licensed. You're free to use it in any project — commercial or personal.

Attribution

Please credit Echo Music Lossless in your app or website with a link back to lossless.echomusic.fun.

Rate Limits

The JSON is hosted on GitHub raw CDN. Avoid polling more than once per minute. For high-traffic apps, mirror the data on your own CDN.

Contribute Back

If your users discover new canvases, encourage them to submit via the Contribute Portal so the whole community benefits.