musicland/plans/suno-status-tracking.md

Plan - Suivi du statut de génération Suno

Objectif

Permettre de suivre la progression d'une génération de musique Suno en utilisant le taskId retourné par l'API.

Problème identifié

• ✅ L'API Suno retourne un taskId après la génération
• ✅ Pas de moyen de suivre la progression de la génération
• ✅ Besoin d'une fonction pour interroger le statut

Solution implémentée

✅ 1. Ajout de la constante API

• Ajouté SUNO_STATUS_PATH = "/api/v1/query" dans music.js
• Endpoint pour interroger le statut d'une tâche

✅ 2. Création de la fonction getSunoStatus

• Nouvelle fonction Cloud Function getSunoStatus
• Prend en paramètre le taskId
• Interroge l'API Suno pour récupérer le statut
• Retourne les données de progression

✅ 3. Export de la fonction

• Ajouté l'export dans index.js
• Fonction accessible via firebase.functions().httpsCallable('getSunoStatus')

Structure de la fonction

exports.getSunoStatus = onCall({}, async ({ data = {} }) => {
  const { taskId } = data;
  
  // Validation du taskId
  // Appel à l'API Suno
  // Parsing de la réponse
  // Retour des données
});

Utilisation côté client

// Après avoir généré la musique et récupéré le taskId
const checkStatus = async (taskId) => {
  try {
    const result = await firebase
      .functions()
      .httpsCallable('getSunoStatus')({ taskId });
    
    console.log('Statut:', result.data);
    return result.data;
  } catch (error) {
    console.error('Erreur:', error);
  }
};

// Polling pour suivre la progression
const pollStatus = async (taskId) => {
  const interval = setInterval(async () => {
    const status = await checkStatus(taskId);
    
    if (status?.data?.status === 'completed') {
      clearInterval(interval);
      console.log('🎵 Génération terminée!');
    }
  }, 5000); // Vérifier toutes les 5 secondes
};

Réponse de la fonction

Succès

{
  "success": true,
  "taskId": "aa6920a5a84317c40688b6c4e457c630",
  "data": {
    "status": "processing", // ou "completed", "failed"
    "progress": 75,
    "audio_url": "https://...",
    "video_url": "https://...",
    "image_url": "https://..."
  }
}

Erreur

{
  "error": "Erreur lors de la vérification du statut: TaskId manquant"
}

Statuts possibles

• pending : En attente de traitement
• processing : En cours de génération
• completed : Génération terminée avec succès
• failed : Échec de la génération
• cancelled : Génération annulée

Gestion des erreurs

• ✅ Validation du taskId obligatoire
• ✅ Gestion des erreurs de réseau
• ✅ Parsing sécurisé de la réponse JSON
• ✅ Logs avec émojis pour le debugging
• ✅ Messages d'erreur explicites

Prochaines étapes

• Déployer les fonctions : firebase deploy --only functions
• Tester la fonction avec un taskId réel
• Implémenter le polling côté client
• Ajouter une interface utilisateur pour afficher la progression
• Gérer les cas d'erreur côté client

Exemple d'intégration complète

// 1. Générer la musique
const generateResult = await firebase
  .functions()
  .httpsCallable('music-generateMusic')(musicData);

const taskId = generateResult.data.response.data.taskId;

// 2. Suivre la progression
if (taskId) {
  pollStatus(taskId);
} else {
  console.error('❌ TaskId manquant');
}

Notes importantes

• ⚠️ Ne pas interroger l'API trop fréquemment (max toutes les 5 secondes)
• ⚠️ Implémenter un timeout pour éviter les boucles infinies
• ⚠️ Gérer les cas où le taskId n'existe plus
• ⚠️ La génération peut prendre 2-3 minutes selon la complexité

Fichiers modifiés

• ✅ /functions/src/music.js - Ajout de getSunoStatus
• ✅ /functions/index.js - Export de la fonction
• ✅ /plans/suno-status-tracking.md - Ce fichier de documentation