Documentation API

Introduction

L'API TrackCue vous permet d'intégrer l'analyse audio (BPM, tonalité, cue points, stems) à vos propres workflows — scripts, apps custom, intégrations DAW/DJ.

Toutes les réponses sont au format JSON. Les timestamps sont en ISO 8601 UTC. Les durées sont en secondes (float), les fréquences en Hz.

Authentification

L'API utilise des JWT Bearer tokens. Obtenez un access token via l'endpoint /auth/login, puis passez-le dans le header Authorization: Bearer <token>.

Connexion

# Body (JSON)
{
  "identifier": "[email protected]",
  "password": "votre-mot-de-passe"
}

# Réponse
{
  "access_token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "token_type": "bearer",
  "expires_in": 3600
}

Rafraîchir un token

# Body (JSON)
{ "refresh_token": "eyJhbGc..." }

Exemple d'appel authentifié

curl https://trackcue.app/api/v1/tracks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Rate limits

Les limites dépendent de votre plan. Les headers X-RateLimit-* sont retournés sur chaque réponse.

Une erreur 429 Too Many Requests est renvoyée si vous dépassez la limite. Respectez le header Retry-After (en secondes).

Tracks

La ressource Track représente un morceau uploadé — avec ses métadonnées (titre, artiste, durée) et les résultats d'analyse (BPM, key, énergie, cue points).

Lister ses tracks

Uploader un morceau

Multipart form-data avec le fichier dans le champ file. L'analyse démarre automatiquement en background. Utilisez cue_mode pour choisir : auto, on_demand, pro.

curl -X POST https://trackcue.app/api/v1/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "[email protected]" \
  -F "cue_mode=auto"

Récupérer un track

Supprimer un track

Analyse audio

TrackCue calcule automatiquement : BPM (tempo), key (tonalité Camelot + musicale), énergie (0→1), cue points (intro / drop / outro), waveform (peaks) et stems (voix/drums/bass/autres).

Objet Analysis

{
  "track_id": "trk_abc123",
  "bpm": 128.03,
  "key": "8A",
  "key_musical": "A minor",
  "energy": 0.78,
  "danceability": 0.84,
  "duration_s": 242.5,
  "cue_points": [
    { "type": "intro",  "time_s": 0.0   },
    { "type": "drop",   "time_s": 62.4  },
    { "type": "outro",  "time_s": 210.1 }
  ],
  "stems_available": "true",
  "status": "completed"
}

Comparer deux tracks

Retourne un score de compatibilité harmonique et un delta BPM.

Recommandations

Playlists & Sets

Organisez vos tracks en Playlists (listes libres) ou Sets (ordres optimisés pour un gig — BPM progressif, compatibilité harmonique).

Lister ses sets

Créer un set

{
  "name": "Festival Mix #3",
  "track_ids": ["trk_1", "trk_2", "trk_3"],
  "target_bpm_start": 120,
  "target_bpm_end": 135
}

Optimiser l'ordre d'un set

Export

Exportez vos tracks et sets vers vos logiciels de DJ préférés — Rekordbox, Serato, Traktor, ou M3U/JSON générique.

Exporter un set

Réponse : URL signée vers le fichier d'export (valide 1h).

Webhooks

Recevez des notifications HTTP en push quand un événement survient — utile pour attendre la fin d'une analyse longue sans polling.

Événements supportés

• track.analysis.completed — l'analyse d'un morceau est terminée
• track.analysis.failed — l'analyse a échoué
• track.stems.ready — les stems sont disponibles
• set.exported — un export est généré

Enregistrer un webhook

{
  "url": "https://mon-app.com/webhook/trackcue",
  "events": ["track.analysis.completed"],
  "secret": "whsec_..."
}

Chaque payload est signé avec le header X-TrackCue-Signature: sha256=<hmac> — vérifiez-le côté serveur pour garantir l'origine.

SDKs

Des SDKs officiels sont en cours de développement :

• Python — pip install trackcue (bientôt)
• Node.js — npm install @trackcue/sdk (bientôt)
• Go — go get github.com/trackcue/go (prévu)

En attendant, tous les endpoints sont standard REST — n'importe quel client HTTP fait l'affaire.