Contratti API
TuneCamp espone un'API RESTful per la comunicazione tra la webapp e il backend, oltre a endpoint dedicati per ActivityPub e per il protocollo Subsonic. La specifica OpenAPI completa è contenuta in openapi.yml.
Autenticazione
La maggior parte degli endpoint richiede un JWT (JSON Web Token) nell'intestazione Authorization:
Authorization: Bearer <token>È possibile ottenere un token inviando le proprie credenziali tramite una richiesta POST a /api/auth/login.
Endpoint Principali
Autenticazione (/api/auth)
| Metodo | Percorso | Descrizione |
|---|---|---|
POST | /api/users/register | Registra un nuovo utente |
POST | /api/auth/login | Autentica l'utente e restituisce un JWT |
GET | /api/auth/status | Restituisce la sessione corrente e il profilo utente |
Catalogo Musicale (/api/catalog, /api/tracks, /api/albums)
| Metodo | Percorso | Descrizione |
|---|---|---|
GET | /api/albums | Elenca tutti gli album locali. Restituisce status (draft | published) e is_release (booleano) per distinguere i contenuti della libreria dalle release ufficiali |
GET | /api/albums/:id | Dettagli dell'album, inclusa la lista delle tracce |
GET | /api/artists | Elenca tutti gli artisti |
POST | /api/tracks | Crea una traccia dai metadati (un link, o una riga in attesa del suo file). L'audio non viene scaricato: la traccia nasce senza file_path finché non le si carica un file. Qui non esiste alcuna opzione localize — questo server non scarica audio dalle piattaforme di streaming |
GET | /api/tracks | Elenca le tracce visibili al chiamante. Ogni riga porta downloadable: se QUESTO utente può prendere il file, non solo ascoltarlo (i client che offrono un pulsante di download lo leggono invece di tirare a indovinare) |
GET | /api/tracks/:id | Metadati della traccia |
GET | /api/tracks/:id/stream | Stream audio binario (supporta l'intestazione Range per le tracce cloud) |
GET | /api/tracks/:id/download | Scarica il file audio locale di una singola traccia. Vincolato alla modalità di distribuzione della release: il contenuto a pagamento richiede un codice di sblocco (?code=), un acquisto registrato o un abbonamento attivo (altrimenti 402); le release solo-streaming ed external showcase rispondono 403. Staff, proprietario e artista collegato scavalcano il gate |
POST | /api/tracks/:id/localize | Solo admin: copia una traccia su cloud (percorso gdrive://) in un file locale durevole. Le piattaforme di streaming vengono rifiutate con 400 — si usa Sidecamp |
GET | /api/albums/:id/download | Scarica uno ZIP dei file audio locali dell'album (esclude le tracce streaming/linkate). Stesso gate sulla modalità di distribuzione della rotta a traccia singola |
GET | /api/releases/:id/download | Scarica uno ZIP dei file audio locali di una release. Risolve id numerico o slug; le release private sono limitate a proprietario/admin e vale lo stesso gate sulla modalità di distribuzione della rotta a traccia singola |
GET | /api/waveform/:id | Dati della forma d'onda per la visualizzazione grafica |
GET | /api/releases/:id/artwork/:filename | Serve in modo sicuro gli artwork aggiuntivi delle release |
Campioni Gratuiti / Samples (/api/samples)
| Metodo | Percorso | Descrizione |
|---|---|---|
GET | /api/samples | Elenca i campioni approvati. mine=true limita ai caricamenti del chiamante (qualsiasi stato); q filtra per termine di ricerca |
GET | /api/samples/moderation/pending | Root-admin/admin/super-user: elenca i campioni in attesa di moderazione/curatela |
GET | /api/samples/:id | Metadati del campione |
GET | /api/samples/:id/download | Scarica il file audio del campione. Supporta autenticazione tramite query ?token= (i campioni approvati sono pubblici; i campioni in sospeso richiedono il proprietario o un moderatore) |
POST | /api/samples | Carica un campione (multipart/form-data: file, title, description, bpm, musicalKey, license, attributionName, tags). Inizia nello stato pending |
PUT | /api/samples/:id | Aggiorna i metadati del campione (proprietario o moderatore) |
DELETE | /api/samples/:id | Elimina un campione (proprietario o moderatore) |
POST | /api/samples/:id/approve | Root-admin/admin/super-user: approva un campione in sospeso |
POST | /api/samples/:id/reject | Root-admin/admin/super-user: rifiuta un campione in sospeso con note opzionali |
I campioni gratuiti non sono asset di vendita: nessun prezzo, nessun flusso di acquisto o crediti. La licenza è una tra cc0, cc-by, cc-by-sa, royalty-free. Il caricamento è raggiungibile da /publish; la gestione dei propri caricamenti si trova nella scheda "Samples" su /my-music; la moderazione si trova in "Sample Curation" su /admin.
Pacchetti di Campioni / Sample Packs (/api/sample-packs)
| Metodo | Percorso | Descrizione |
|---|---|---|
GET | /api/sample-packs | Elenca i pacchetti approvati. mine=true limita ai propri pack (qualsiasi stato); q filtra per ricerca |
GET | /api/sample-packs/moderation/pending | Root-admin/admin/super-user: elenca i pack in attesa di moderazione |
GET | /api/sample-packs/:id | Metadati del pack inclusi i campioni membri |
GET | /api/sample-packs/:id/cover | Immagine di copertina del pack; fallback su SVG segnaposto se non impostata |
POST | /api/sample-packs | Carica più file contemporaneamente come pack (multipart/form-data: files[], title, description, license, attributionName). Stesse regole di pubblicazione di /api/samples; inizia in pending salvo auto-approvazione |
POST | /api/sample-packs/:id/cover | Imposta/sostituisce la copertina del pack (multipart/form-data: cover). Solo proprietario o moderatore |
PUT | /api/sample-packs/:id | Aggiorna i metadati del pack (proprietario o moderatore) |
DELETE | /api/sample-packs/:id | Elimina un pack e tutti i campioni associati (proprietario o moderatore) |
POST | /api/sample-packs/:id/approve | Root-admin/admin/super-user: approva un pack in sospeso (a cascata sui suoi campioni) |
POST | /api/sample-packs/:id/reject | Root-admin/admin/super-user: rifiuta un pack in sospeso con note opzionali |
Un campione inserito in un pack (samples.pack_id impostato) è escluso dall'elenco pubblico di /api/samples ed emerge unicamente attraverso il rispettivo pack.
Collab (/api/collab)
Tutte le route richiedono l'autenticazione. Vedi COLLAB.md per la documentazione completa.
| Metodo | Percorso | Descrizione |
|---|---|---|
GET | /api/collab | Elenca i progetti condivisi. mine=true limita ai propri |
GET | /api/collab/:id | Metadati del progetto con relative versioni e stem |
POST | /api/collab | Crea un progetto (richiede canPublishContent) |
DELETE | /api/collab/:id | Elimina un progetto e i suoi stem (solo proprietario) |
POST | /api/collab/:id/versions | Salva uno snapshot di versione append-only (state, note opzionale) |
POST | /api/collab/:id/stems | Carica uno stem audio (multipart/form-data: file, nome opzionale) |
GET | /api/collab/:id/stems/:stemId/download | Esegue lo streaming audio di uno stem |
DELETE | /api/collab/:id/stems/:stemId | Elimina uno stem (autore dello stem o proprietario del progetto) |
Pagamenti e Monetizzazione (/api/payments)
| Metodo | Percorso | Descrizione |
|---|---|---|
POST | /api/payments/stripe/create-session | Crea una sessione di Stripe Checkout per acquisti in valuta fiat |
POST | /api/payments/stripe/create-trackcap-session | Crea una sessione di Stripe Checkout per acquistare slot aggiuntivi per il caricamento di tracce |
GET | /api/payments/onramp-config | Configurazione di Stripe Crypto Onramp |
POST | /api/payments/verify | Verifica una transazione on-chain (ETH/USDC) su Base |
GET | /api/payments/download/:trackId?code=... | Scarica una traccia acquistata tramite codice di sblocco |
GET | /api/payments/rate/USD | Tasso di cambio corrente ETH/USD |
Archiviazione e Cloud (/api/storage)
| Metodo | Percorso | Descrizione |
|---|---|---|
GET | /api/storage/gdrive/auth | Avvia il flusso OAuth2 di Google Drive |
GET | /api/storage/gdrive/files | Elenca file e cartelle su Google Drive |
POST | /api/storage/gdrive/import | Importa un file di Drive come riferimento gdrive:// |
POST | /api/storage/gdrive/localize/:id | Scarica permanentemente un file cloud sul server locale |
Metadati e Ricerca Esterna (/api/metadata)
| Metodo | Percorso | Descrizione |
|---|---|---|
GET | /api/metadata/search?q=... | Cerca i metadati dell'album tra i provider esterni (MusicBrainz, Discogs, iTunes, TheAudioDB) |
GET | /api/metadata/lyrics?artist=...&title=... | Recupera i testi delle canzoni tramite Lyrics.ovh |
POST | /api/metadata/apply | Applica i metadati selezionati a una traccia locale |
Social, Commenti e Post (/api/artists, /api/comments, /api/ap)
| Metodo | Percorso | Descrizione |
|---|---|---|
GET | /api/artists/:id/posts | Elenca i post pubblici di un artista |
POST | /api/admin/posts | Crea un nuovo post (solo per amministratori) |
GET | /api/comments/track/:trackId | Elenca i commenti per una traccia specifica |
POST | /api/comments/track/:trackId | Aggiunge un commento (richiede autenticazione) |
GET | /api/ap/timeline/:artistId | Attività recente degli attori seguiti |
GET | /api/ap/users/:slug | Profilo ActivityPub (actor) per un utente locale |
POST | /api/ap/inbox | Riceve messaggi ActivityPub remoti in entrata |
POST | /api/releases/:id/report | Segnala una release per violazione di copyright o contenuti inappropriati |
GET | /api/admin/reports | Elenca tutte le segnalazioni attive di release (solo amministratori) |
DELETE | /api/admin/reports/:id | Risolve o archivia una segnalazione (solo amministratori) |
Amministrazione (/api/admin)
| Metodo | Percorso | Descrizione |
|---|---|---|
GET | /api/admin/system/users | Elenca gli utenti registrati (solo per amministratori) |
POST | /api/admin/system/rescan | Avvia una scansione completa della libreria |
POST | /api/admin/upload/tracks | Archivia uno o più file audio e li importa nella libreria (solo admin/artisti). releaseSlug li collega a una release; artist/album ne indicano il contenitore. title e trackNum impostano titolo e posizione di una traccia e valgono solo se viene inviato un singolo file — con più file ciascuno mantiene i propri tag. Li usa l'editor delle release per riempire una tracklist importata, i cui file raramente sono taggati come la release li elenca |
POST | /api/admin/upload/additional-artworks | Carica più artwork/booklet aggiuntivi per una release (solo admin/artisti) |
GET | /api/admin/stats | Statistiche di utilizzo del server e del database |
GET | /api/admin/system/resources | Snapshot in tempo reale delle risorse del processo/host — CPU, memoria, RAM dell'host, dimensioni del database SQLite e attività in background in esecuzione (solo per amministratori root) |
GET | /api/admin/storage/overview | Utilizzo del disco a livello di istanza e suddivisione per utente (solo per amministratori root) |
L'acquisizione di contenuti P2P (Soulseek, BitTorrent, yt-dlp) è stata spostata dal backend all'app desktop Sidecamp; i precedenti endpoint
/api/admin/torrents*non esistono più.
Radio (/api/radio)
Una singola stazione sempre attiva che trasmette in streaming il catalogo dell'istanza. L'avvio/arresto è riservato agli amministratori; lo stream e i feed sono pubblici.
| Metodo | Percorso | Descrizione |
|---|---|---|
GET | /api/radio | Stato corrente della stazione (traccia in riproduzione, numero di ascoltatori) |
POST | /api/radio/start | Avvia la stazione (solo per amministratori) |
POST | /api/radio/stop | Ferma la stazione (solo per amministratori) |
GET | /api/radio/stream.m3u | Playlist M3U per lettori esterni |
GET | /api/radio/feed.rss | Feed RSS della stazione |
GET | /api/radio/hls/:file | Playlist/segmenti HLS per la riproduzione nel browser |
Protocolli di Terze Parti
API Subsonic (/rest)
TuneCamp implementa il protocollo Subsonic (v1.16.1) per la compatibilità con i client mobili esistenti come DSub, Symfonium, Tempo e Substreamer.
- Percorso di base:
/rest/*.view - I metodi supportati includono:
getAlbumList,getMusicDirectory,streame altri.
Consulta SUBSONIC.md per la tabella di compatibilità completa.
Model Context Protocol (/api/mcp)
TuneCamp implementa il protocollo MCP in modo che i client IA esterni possano interrogare il catalogo e le statistiche del server.
| Metodo | Percorso | Descrizione |
|---|---|---|
GET | /api/mcp/sse | Apre il canale asincrono SSE. Richiede autenticazione Bearer tc_... |
POST | /api/mcp/message | Invia una richiesta JSON-RPC dal client al server |
Vedi mcp-setup-guide.md per la configurazione del client.
Formato delle Risposte
Tutte le risposte delle API (eccetto gli stream audio) sono in formato JSON. In caso di errore, il server restituisce un codice di stato HTTP appropriato e un oggetto di errore:
json
{
"error": "Messaggio di errore descrittivo"
}