Preflight QC

Preflight QC è un componente aggiuntivo premium che ti offre un controllo qualità professionale delle release. Invia una release e Preflight QC la analizza da cima a fondo: metadati, date di uscita, audio, copertina, contenuti IA, identificativi di catalogo, distribuzione precedente e documentazione delle licenze. Ricevi un rapporto di qualità chiaro e su cui agire. Correggi ciò che segnala con i tuoi tempi, poi conferma la release per la revisione quando sei soddisfatto.

Per etichette e integratori dell’API, Preflight QC funziona come un mattone su cui costruire. Recupera il rapporto di qualità in modo programmatico, collegalo alla tua pipeline di QA, vincola il tuo processo interno di approvazione ai suoi risultati e conferma le release per la revisione in automatico. Il tuo team fissa l’asticella della qualità e Preflight QC fa l’analisi.

Una release che arriva pulita attraversa la revisione in fretta. Preflight QC ti ci porta prima ancora di inviarla.

Che cos’è Preflight QC

Con Preflight QC attivo sul tuo account, l’invio di una release per la distribuzione non la manda direttamente nella coda di revisione. La release entra invece in attesa pre-revisione (“in attesa della tua revisione”) mentre Preflight QC esegue la sua analisi di qualità: metadati, date di uscita, audio, copertina, contenuti IA, identificativi di catalogo, distribuzione precedente e documentazione delle licenze. Il risultato è un rapporto di qualità, e cosa costruirci sopra dipende da te:

• Il tuo processo di QA (API). Fai passare il tuo catalogo dall’analisi di qualità, recupera il rapporto in modo programmatico nella tua pipeline di QA, vincola il tuo processo interno di approvazione ai risultati e conferma ogni release per la revisione solo quando supera la tua asticella. Vedi Usare l’API per le integrazioni.
• Il flusso nell’app. Leggi il rapporto nella pagina della release, correggi ciò che segnala e conferma quando sei soddisfatto.

In entrambi i casi, è la conferma a spostare la release nella coda di revisione normale: nulla entra in revisione finché non dai il via libera.

Preflight QC aggiunge una fase di qualità prima della revisione. Non cambia ciò che accade dopo: una volta che confermi, la tua release segue lo stesso processo di validazione e revisione di qualsiasi altra release.

Come ottenere Preflight QC

Preflight QC è un componente aggiuntivo premium attivato per account dal nostro team. Per attivarlo sul tuo account, contatta il nostro team commerciale e comunica che desideri Preflight QC.

Una volta attivato, vedrai il nuovo passaggio di attesa e conferma alla prossima release che invii per la distribuzione.

Il flusso di lavoro di Preflight QC

Ecco il percorso completo di una release con Preflight QC attivo, dall’invio alla revisione.

1. Invia la tua release per la distribuzione

Crea e completa la tua release come al solito, poi inviala per la distribuzione. Con Preflight QC attivo, questo non mette subito la release nella coda di revisione. La release passa invece in attesa pre-revisione e viene contrassegnata come in attesa della tua revisione.

2. Viene eseguita l’analisi di qualità

Mentre la tua release è in attesa, Preflight QC la analizza da cima a fondo. L’analisi copre:

• Metadati: titoli, artisti, crediti e altri dettagli della release e delle tracce
• Date di uscita: la configurazione delle date e le versioni della release
• Audio: i file audio che hai caricato
• Copertina: l’immagine di copertina
• Contenuti IA: se l’uso dell’IA è dichiarato e la musica o le copertine generate dall’IA che rileviamo
• Identificativi di catalogo: se i tuoi ISRC sono validi e se una registrazione è già stata rivendicata da un altro titolare dei diritti
• Distribuzione precedente: se la release o le sue tracce sono già sugli store tramite un altro distributore
• Licenze: quando una cover, un sample o simili richiedono documentazione a supporto

L’analisi di solito termina qualche minuto dopo il completamento del caricamento e della transcodifica. Mentre è ancora in corso, il rapporto di qualità indica che i controlli sono in corso e non elenca ancora alcun problema.

3. Leggi il tuo rapporto di qualità

Una volta terminata l’analisi, apri il rapporto di qualità della release per vedere cosa richiede la tua attenzione, se c’è qualcosa. Puoi leggerlo in due punti:

• Tramite l’API pubblica, per la tua pipeline di QA; vedi Usare l’API più sotto.
• Nell’app, nella pagina della release.

Il rapporto elenca ogni problema con un titolo chiaro e un messaggio che descrive cosa correggere. Vedi Capire il rapporto di qualità per sapere come leggere i campi.

4. Correggi ciò che è segnalato

Passa in rassegna i problemi del tuo rapporto:

• Problemi di metadati: modifica i dettagli della release o della traccia.
• Problemi di audio o copertina: sostituisci il file interessato.
• Problemi che richiedono un riscontro: rispondi nel thread di note del problema oppure carica il documento richiesto (ad esempio, una licenza per una cover o un sample).

Modificare la tua release mentre è in attesa contrassegna il rapporto attuale come obsoleto: i risultati non riflettono più lo stato più recente della tua release. Modifica quanto vuoi, poi richiedi una nuova analisi, dalla pagina della release nell’app oppure tramite l’endpoint di aggiornamento per le integrazioni. L’analisi viene rieseguita e il rapporto si aggiorna con i nuovi risultati. Puoi ripetere questo ciclo tutte le volte che ti servono, entro un limite di uso corretto su quante nuove analisi puoi avviare per release all’ora.

5. Conferma la release

Quando il tuo rapporto è pulito, o hai affrontato tutto ciò che ti serviva, conferma la release. Nell’app è un pulsante di conferma sulla release; per le integrazioni è l’endpoint di conferma.

La conferma toglie la release dall’attesa e la sposta nella coda di revisione normale. La conferma richiede un’analisi completa e aggiornata: se hai modificato la release dopo l’ultima esecuzione, il rapporto è obsoleto, quindi richiedi una nuova analisi e lascia che finisca prima di confermare.

6. Revisione normale

Dopo la conferma, la tua release viene revisionata esattamente come qualsiasi altra. Per sapere cosa accade durante la revisione, i tempi e i possibili esiti, vedi Validazione e revisione.

Capire il rapporto di qualità

Il rapporto di qualità ha due parti: un elenco di problemi e un piccolo blocco di dettagli del report sull’esecuzione stessa.

Problemi

Ogni problema nel rapporto descrive un aspetto da esaminare. I campi con cui lavorerai:

Campo	Cosa ti indica
Titolo	Un nome breve e in linguaggio semplice per il problema.
Messaggio	In cosa consiste il problema e cosa fare al riguardo.
Gravità	L’importanza del problema, per aiutarti a dare le priorità.
Bloccante	Se il problema deve essere risolto prima di poter confermare (vedi sotto).
Richiede un riscontro	Se il problema necessita di una risposta scritta o di un documento caricato da te.
Descrizione personalizzata	Dettagli aggiuntivi specifici della tua release, quando disponibili.
Tracce interessate	A quali tracce si applica il problema. I problemi a livello di release non elencano tracce specifiche.
Prove	Sui problemi di date, duplicati e distribuzione precedente, le release corrispondenti che abbiamo trovato, così puoi verificare tu stesso il conflitto (vedi sotto).

Bloccante o informativo

• I problemi bloccanti devono essere risolti prima di poter confermare la release per la revisione. Correggi ciò che descrivono, esegui una nuova analisi e spariranno dal tuo rapporto.
• I problemi informativi sono lì per segnalare qualcosa che vale la pena guardare, ma non ti impediscono di confermare. Esaminali e conferma quando sei pronto.

Problemi che richiedono un riscontro

Alcuni problemi non si risolvono con la sola modifica: richiedono qualcosa da parte tua, come una spiegazione scritta o un documento a supporto (ad esempio, una licenza per una cover o un sample). Sono contrassegnati come richiede un riscontro. Per risolverne uno, rispondi nel thread di note del problema o carica il documento richiesto prima di confermare.

Prove su un problema

Alcuni problemi includono delle prove per aiutarti a verificare una segnalazione senza tirare a indovinare: le release esistenti che abbiamo confrontato con la tua. Le vedrai sui problemi di date, duplicati e distribuzione precedente. Ogni corrispondenza mostra il titolo e l’artista della traccia corrispondente, il titolo della sua release, la data di uscita e l’ISRC, oltre a un link a uno store dove quella release è disponibile, e quali delle tue tracce interessa. Vengono elencate fino a tre corrispondenze per traccia. Usa le prove per confermare se il conflitto è reale (ad esempio, un caricamento precedente tuo) prima di decidere come rispondere.

I dettagli del report

Accanto ai problemi, il report include alcuni dettagli sull’esecuzione:

Campo	Cosa ti indica
generated_at	Quando è stato prodotto il report attuale. È vuoto mentre la prima analisi è ancora in corso.
checks_in_progress	true mentre l’analisi è ancora in corso; l’elenco dei problemi resta vuoto finché non termina.
stale	true quando hai modificato la release (o una qualsiasi delle sue tracce) dopo l’ultima analisi completata, per cui i risultati non riflettono più lo stato attuale. Qualsiasi modifica conta. Richiedi una nuova analisi per aggiornare il report.
hold	Se la release è attualmente in attesa pre-revisione.
review_status	Lo stato di revisione attuale della release.
release_status	Lo stato complessivo della release stessa, accanto allo stato specifico della revisione.
profile	Il profilo di qualità applicato a questa release, con il suo nome e la sua versione.

Usare l’API per le integrazioni

Se sviluppi sull’API pubblica di LabelGrid, puoi collegare Preflight QC alla tua pipeline: fai passare ogni release dall’analisi di qualità, recupera il rapporto nel tuo processo di QA, vincola il tuo processo interno di approvazione ai risultati e conferma per la revisione dai tuoi strumenti. Preflight QC fornisce tre endpoint per questo, tutti con la stessa autenticazione con token Bearer del resto dell’API pubblica. Per gli schemi completi e sempre aggiornati di richiesta e risposta, vedi il riferimento dell’API.

Webhook: scopri quando il rapporto è pronto

Invece di interrogare i risultati a intervalli regolari, puoi far sì che LabelGrid ti avvisi nel momento in cui un rapporto è pronto. Iscriviti all’evento di webhook release.preflight.report_ready: si attiva non appena Preflight QC termina di analizzare una release in attesa pre-revisione, incluse tutte le volte in cui si completa una nuova analisi che richiedi. Ricevi esattamente un evento per ciclo di analisi.

Iscriviti allo stesso modo in cui ti iscrivi agli altri eventi di webhook delle release di LabelGrid, dalle impostazioni dei webhook nell’app o tramite l’API. Ogni evento trasporta un riepilogo compatto dell’esecuzione, mai i problemi stessi:

• Identificatori della release: release_id, label_id, release_cat e release_title.
• generated_at: quando è stato prodotto questo rapporto. Corrisponde al generated_at del rapporto stesso.
• profile: il profilo di qualità attraverso cui sono stati calcolati i conteggi, nella forma {name, version}.
• counts: i totali blocking, informational e requires_feedback. Il conteggio requires_feedback si sovrappone agli altri due.

Usa i conteggi per decidere se devi agire, poi recupera il rapporto stesso per il dettaglio. Lo schema di integrazione consigliato:

1. Iscriviti a release.preflight.report_ready.
2. A ogni evento, chiama Ottenere il rapporto di qualità per leggere l’insieme completo dei problemi.
3. Correggi e riesegui: dopo aver modificato una release in attesa, chiama l’endpoint di aggiornamento per avviare una nuova analisi; il webhook si attiva di nuovo quando si completa.
4. Decidi e conferma dai tuoi strumenti una volta che la release supera la tua asticella.

Per il riferimento completo del payload e il funzionamento dei webhook (la firma, i tentativi ripetuti e l’involucro), vedi Webhooks.

Ottenere il rapporto di qualità

GET /api/public/releases/{id}/quality-report
Authorization: Bearer YOUR_API_TOKEN

Restituisce il rapporto di qualità attuale della release. La risposta contiene:

• issues[]: una voce per problema, ciascuna con id, code (una stringa stabile; vedi Lavorare con i codici dei problemi), title, message, status, severity, is_blocking, requires_feedback, custom_description e affected_tracks. Sui problemi di date, duplicati e distribuzione precedente, la voce porta anche un array evidence (vedi sotto).
• report: generated_at, checks_in_progress, stale, hold, review_status, release_status e profile (un oggetto con name e version). stale è true quando la release o una qualsiasi delle sue tracce è stata modificata dopo l’ultima analisi completata; riesegui l’analisi con l’endpoint di aggiornamento prima di confermare.

Mentre l’analisi è ancora in corso, il report restituisce checks_in_progress: true con un elenco issues vuoto. Se preferisci non usare i webhook, interroga questo endpoint a intervalli regolari finché generated_at non è valorizzato, di solito qualche minuto dopo il termine del caricamento e della transcodifica, poi leggi i problemi. Per essere avvisato nel momento in cui il report è pronto, usa invece il webhook di rapporto pronto.

Un esempio di risposta ad analisi terminata:

{
  "issues": [
    {
      "id": "12345",
      "code": "example.issue-code",
      "title": "Short issue title",
      "message": "What to fix and how.",
      "status": "confirmed",
      "severity": "…",
      "is_blocking": true,
      "requires_feedback": false,
      "custom_description": null,
      "affected_tracks": [456],
      "evidence": [
        {
          "affected_track_id": 456,
          "track_title": "Matched track title",
          "artist": "Matched artist",
          "release_title": "Matched release",
          "release_date": "2024-03-01",
          "isrc": "USRC12345678",
          "store_url": "https://…"
        }
      ]
    }
  ],
  "report": {
    "generated_at": "2026-07-07T12:00:00Z",
    "checks_in_progress": false,
    "stale": false,
    "hold": true,
    "review_status": "…",
    "release_status": "…",
    "profile": { "name": "quality_report", "version": 2 }
  }
}

Ogni elemento di evidence descrive una release esistente che ha corrisposto alla tua: affected_track_id (a quale delle tue tracce si applica la corrispondenza), i corrispondenti track_title, artist, release_title, release_date e isrc, e uno store_url che punta a una pagina di uno store dove la corrispondenza è disponibile. Vengono elencate al massimo tre corrispondenze per traccia, e la chiave è presente solo sui tipi di problema sopra indicati.

Richiedere una nuova analisi

POST /api/public/releases/{id}/quality-report/refresh
Authorization: Bearer YOUR_API_TOKEN

Avvia un nuovo ciclo di analisi Preflight QC per una release in attesa. Modificare una release in attesa non riesegue i controlli da solo: contrassegna soltanto il rapporto attuale come obsoleto (report.stale: true). Quando hai finito di modificare, chiama questo endpoint per rieseguire l’analisi; quando il ciclo si completa, il webhook di rapporto pronto si attiva e report.stale torna a false.

Una chiamata riuscita restituisce 202 Accepted:

{
  "status": "refreshing",
  "checks_in_progress": true,
  "review_status": "pending_customer_review",
  "release_status": "to_review"
}

La chiamata è idempotente mentre un ciclo è in corso: richiamarla restituisce lo stesso corpo di analisi in corso, non mette in coda una seconda analisi e non incide sul tuo budget. Altre risposte da gestire:

• 409 not_in_customer_review_hold: la release non è attualmente in attesa per la tua revisione Preflight QC.
• 409 refresh_coalesced: un’analisi di questa release si è completata un attimo fa, quindi non è stato messo in coda nulla. Riprova dopo l’intervallo indicato dall’header Retry-After (in secondi).
• 429 preflight_recheck_limit_reached: hai raggiunto il budget di uso corretto di 6 cicli di analisi avviati per release per ora mobile. L’header Retry-After (in secondi) ti indica quando è consentito il prossimo aggiornamento. Interrogare un’analisi in corso è gratuito; solo avviare un nuovo ciclo consuma budget.
• 403 RELEASE_NOT_VALIDATED: la release deve superare la validazione prima che possa iniziare una nuova analisi (la stessa regola della distribuzione); esegui prima la validazione.
• 403 pre_review_qc_not_enabled: Preflight QC non è abilitato per l’account proprietario.

Confermare la release per la revisione

POST /api/public/releases/{id}/confirm-review
Authorization: Bearer YOUR_API_TOKEN

Toglie la release dall’attesa e la sposta nella coda di revisione normale: l’equivalente via API del pulsante di conferma nell’app.

La conferma richiede un’analisi completa e aggiornata. Due conflitti da gestire:

• 409 checks_in_progress: l’analisi è ancora in corso. Attendi il webhook di rapporto pronto (oppure interroga finché generated_at non è valorizzato), poi riprova.
• 409 checks_stale: la release è stata modificata dopo l’ultima analisi completata (report.stale è true). Chiama l’endpoint di aggiornamento, attendi il nuovo rapporto, poi riprova la conferma.

Nota

Mentre una release è in attesa pre-revisione, inviarla tramite la normale via di distribuzione restituisce 409 preflight_recheck_required: una release in attesa esce dall’attesa solo tramite il flusso di aggiornamento e conferma descritto qui.

Lavorare con i codici dei problemi

Se costruisci logica sopra il rapporto di qualità, basala sul code del problema:

• code è una stringa stabile in formato slug (ad esempio, audio.trailing-silence). Puoi mappare i codici nel tuo sistema e costruirci sopra la tua logica in sicurezza.
• Titoli e messaggi sono testi per le persone. Possono essere rifiniti nel tempo, quindi non basare mai la logica sul testo; usalo solo per la visualizzazione.
• Possono comparire nuovi codici man mano che la copertura di Preflight QC si amplia. Gestisci i codici che non riconosci in modo generico: mostra title e message dalla risposta invece di andare in errore.
• I tuoi rapporti ti insegnano i codici che contano. Man mano che fai passare le release da Preflight QC, i codici rilevanti per il tuo catalogo emergono naturalmente nei tuoi rapporti di qualità.
• Cosa copre l’analisi. I problemi rientrano in queste categorie: metadati di release e tracce, date e versioni della release, qualità audio, copertina, contenuti IA, identificativi di catalogo, distribuzione precedente, licenze e documentazione.

Il catalogo dei problemi

Per mappare i problemi quando costruisci il tuo processo di QA, recupera il catalogo completo in modo programmatico:

GET /api/public/issue-definitions
Authorization: Bearer YOUR_API_TOKEN

Restituisce tutti i problemi che possono comparire in un rapporto di qualità, indicizzati per codice (stringa stabile), con titolo, modello del messaggio, gravità, indicatore bloccante, requires_feedback e la sua categoria (type). La risposta contiene anche il profilo di qualità attraverso cui è stato calcolato il catalogo, nella forma {name, version}. L’endpoint è disponibile solo per gli account con il componente aggiuntivo Preflight QC.

Domande frequenti

E se l’analisi è ancora in corso?

Il report mostrerà checks_in_progress: true senza problemi elencati per ora. È normale subito dopo l’invio. Attendi qualche minuto dopo il termine del caricamento e della transcodifica, poi ricontrolla: nell’app il report si aggiorna da solo. Tramite l’API puoi iscriverti al webhook di rapporto pronto per ricevere una notifica nel momento in cui è pronto, oppure interrogarlo finché generated_at non è valorizzato.

Posso modificare la mia release mentre è in attesa?

Sì, modifica con la massima libertà: una release in attesa pre-revisione resta completamente modificabile. La modifica non riesegue i controlli da sola; contrassegna il rapporto attuale come obsoleto. Quando hai finito le tue modifiche, richiedi una nuova analisi (dalla pagina della release nell’app, oppure l’endpoint di aggiornamento per le integrazioni) per vedere i risultati aggiornati senza uscire dall’attesa. La nuova analisi deve completarsi prima che tu possa confermare.

Cosa succede dopo che confermo?

La tua release lascia l’attesa ed entra nella coda di revisione normale, dove viene revisionata come qualsiasi altra. Vedi Validazione e revisione per sapere come funziona la revisione, quanto dura e i possibili esiti.

Posso riportare una release a bozza?

Sì: finché la tua release è in attesa pre-revisione e non l’hai ancora confermata, non è entrata in revisione, quindi sei libero di continuare a modificarla o di lasciarla come bozza e tornarci più tardi. Entra nella coda di revisione solo quando la confermi.

Devo correggere ogni problema prima di confermare?

Devi risolvere i problemi bloccanti prima di poter confermare. I problemi informativi non ti impediscono di confermare, ma vale la pena guardarli: sistemare quanto più possibile prima della revisione è la via più rapida verso l’approvazione.

---

Domande su Preflight QC? Contatta il nostro team. Saremo felici di aiutarti.