Universal JSON Audio Protocol

Addon Developer Guide

Connect any custom music catalog, private Subsonic/Navidrome server, or FLAC lossless repository to Timbre with just three simple HTTP GET endpoints.

Overview

Timbre never executes arbitrary untrusted remote code. Instead, it interacts with your audio backend over standard HTTP using lightweight JSON messages.

When a track is requested, Timbre searches your catalog, resolves a direct playable stream URL (e.g. uncompressed 24-bit/96kHz FLAC), and feeds it straight to the bit-perfect Android AudioTrack pipeline.

01 • DISCOVERY

GET /manifest.json

Describes addon name, author, capabilities, and supported audio qualities.

02 • CATALOG SEARCH

GET /search?q=...

Matches song title, artist, and album against your catalog.

03 • RESOLUTION

GET /stream/:id

Returns media stream URL, codec format, sample rate, and bit depth.

04 • PLAYBACK

Direct AudioTrack

Plays bit-perfect audio through external USB DAC or local headphones.

Addon Protocol Endpoints

1. Addon Manifest

When a user enters your addon URL (e.g. https://my-audio-addon.com), Timbre fetches /manifest.json to register capabilities and verify server health.

GET /manifest.json
Response (application/json) 
{
  "id": "studio-flac-source",
  "name": "Studio Masters FLAC",
  "description": "High-resolution 24-bit/96kHz lossless audio catalog",
  "version": "1.0.0",
  "author": "Audio Engineering",
  "homepage": "https://sksalapur.github.io/Timbre/",
  "resources": ["search", "stream"],
  "capabilities": {
    "search": true,
    "stream": true,
    "lossless": true,
    "maxSampleRate": 192000,
    "maxBitDepth": 24
  }
}

3. Stream Resolver

Returns the direct media URL and detailed encoding metadata. Providing exact bitDepth and sampleRate allows Timbre's bit-perfect sink to configure your hardware DAC immediately.

GET /stream/{trackId}
Response (application/json) 
{
  "url": "https://stream.example.com/flac/trk_eagles_hotel_california.flac",
  "format": "flac",
  "bitDepth": 24,
  "sampleRate": 96000,
  "bitrate": 4608000,
  "headers": {
    "User-Agent": "Timbre/1.8"
  }
}

Timbre Lossless Pipeline

💎
Pure Hardware Path: Android's default AudioTrack mixer resamples all audio streams to 48kHz. Timbre utilizes direct hardware routing via AndroidX Media3, preserving pristine 24-bit/96kHz and 24-bit/192kHz PCM without downsampling.

Lossless Priority Window (Settings Slider)

Unlike stock players that clumsily start with lossy Opus and swap streams halfway through, Timbre queries your lossless addon first.

In Settings → Playback, users can set the Lossless Priority Window between 0.5s and 5.0s (in 0.5s increments, default 3.5s). Timbre waits up to this duration for the lossless addon to reply. If the track is absent, it gracefully falls back to YouTube Music Opus with zero playback gap.

Supported Codecs

Codec Container Max Precision Android Handling
FLAC .flac / Native 24-bit / 192 kHz Bit-perfect Sink
ALAC .m4a / Apple Lossless 24-bit / 96 kHz Hardware Decoded
AAC .m4a / ADTS 320 kbps High Quality MediaCodec pass-through
Opus .webm / .ogg 160 kbps Adaptive Standard fallback

Reference Implementation & Code Samples

Node.js / Express

server.js (Node 18+) 
const express = require('express');
const cors = require('cors');
const app = express();

app.use(cors());

// 1. Manifest
app.get('/manifest.json', (req, res) => {
  res.json({
    id: 'my-flac-server',
    name: 'My FLAC Server',
    description: 'Personal Hi-Res Audio Addon',
    version: '1.0.0',
    resources: ['search', 'stream'],
    capabilities: { search: true, stream: true, lossless: true }
  });
});

// 2. Search
app.get('/search', (req, res) => {
  const query = req.query.q || '';
  // Query your media index (e.g. SQLite, Subsonic, Deezer, Tidal)
  res.json([
    {
      id: 'song_42',
      title: 'Time',
      artist: 'Pink Floyd',
      album: 'The Dark Side of the Moon',
      duration: 425,
      artworkURL: 'https://example.com/covers/dsotm.jpg'
    }
  ]);
});

// 3. Stream
app.get('/stream/:id', (req, res) => {
  const trackId = req.params.id;
  res.json({
    url: `https://example.com/audio/${trackId}.flac`,
    format: 'flac',
    bitDepth: 24,
    sampleRate: 96000,
    bitrate: 4608000
  });
});

app.listen(3000, () => console.log('Timbre Addon listening on port 3000'));

Python / FastAPI

main.py (FastAPI) 
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()
app.add_middleware(CORSMiddleware, allow_origins=["*"])

@app.get("/manifest.json")
def get_manifest():
    return {
        "id": "py-lossless",
        "name": "Python FLAC Bridge",
        "description": "FastAPI Lossless Resolver",
        "version": "1.0.0",
        "resources": ["search", "stream"],
        "capabilities": {"search": True, "stream": True, "lossless": True}
    }

@app.get("/search")
def search_tracks(q: str = ""):
    return [
        {
            "id": "track_1",
            "title": "Teardrop",
            "artist": "Massive Attack",
            "album": "Mezzanine",
            "duration": 330,
            "artworkURL": "https://example.com/mezzanine.jpg"
        }
    ]

@app.get("/stream/{track_id}")
def get_stream(track_id: str):
    return {
        "url": f"https://example.com/stream/{track_id}.flac",
        "format": "flac",
        "bitDepth": 24,
        "sampleRate": 96000,
        "bitrate": 4608000
    }

Timbre Community & Addon Ecosystem

Looking for community addons, shared configurations, or help setting up your private music server?

Join our official audiophile community on Telegram to discuss DAC pairings, EQ presets, and addon configurations:

Join Timbre Telegram Community →

Installation & Testing in Timbre

  1. Open Timbre on your Android device.
  2. Navigate to Settings → Addons.
  3. Tap Add Addon and enter your server URL (e.g. https://my-addon.example.com).
  4. Timbre will query /manifest.json, validate schema, and display a green active badge.

Verifying Playback in Nerd Stats

While playing any song in Timbre, tap the Nerd Stats button on the player screen to see real-time hardware telemetry:

  • Audio Sink: Verify it displays AudioTrack (Direct) when external USB DAC is connected.
  • Sample Rate: Confirms physical output matches stream master (e.g. 96.0 kHz → 96.0 kHz).
  • Bitrate: Displays full uncompressed PCM data rate (e.g. 4,608 kbps for 24-bit/96kHz).