ACRCloud — Identificació musical

Què és i per a què serveix

ACRCloud és un servei d'audio fingerprinting que permet identificar cançons a partir d'un fragment d'àudio (com Shazam). A LDP s'utilitza per:

• Identificar cançons per micròfon: L'usuari grava uns segons d'àudio i el sistema identifica la cançó i els balls associats
• Recuperar cançons d'importacions antigues: Identificar cançons de vídeos que no tenien informació a la descripció

El sistema té dues parts:

1. Catàleg custom (bucket): Conté les fingerprints de les cançons de LDP (pujades des dels previews de 30s)
2. Reconeixement: Compara àudio del micròfon contra el catàleg

Crear compte

1. Entra a ACRCloud Console
2. Registra't amb email o Google
3. Confirma el compte si cal
4. Queda activada la prova gratuïta de 14 dies

Triar producte

Dins la consola, a Products, tria:

• Audio & Video Recognition (AVR)

NO triïs Broadcast Monitoring ni Songs Metadata and Links.

Crear bucket custom

1. Menú esquerre → Buckets → Custom Files
2. Clica Create Bucket
3. Configuració:

Camp	Valor
Bucket Name	ldp-songs
Labels	Music
Network Type	Online
Region	eu-west-1 (Europa)
Metadata Template	ldp_song_id,title,artist,isrc

4. Clica Confirm

Crear projecte de reconeixement

1. Menú esquerre → Projects → Audio & Video Recognition
2. Clica Create Project
3. Configuració:

Camp	Valor
Project Name	ldp-identify
Audio Source	Recorded Audio (àudio de micròfon, amb soroll ambient)
Audio Engine	Audio Fingerprinting
Buckets	ldp-songs

4. Clica Confirm

Obtenir credencials

A la llista de projectes, a la fila de ldp-identify, copia:

• Access Key
• Secret Key (Access Secret)
• Host (ex: identify-eu-west-1.acrcloud.com)

Variables d'entorn

Al fitxer .env:

ACRCLOUD_ENABLED=true
ACRCLOUD_ACCESS_KEY=<la teva access key>
ACRCLOUD_ACCESS_SECRET=<la teva secret key>
ACRCLOUD_HOST=<el host del teu projecte>
ACRCLOUD_BUCKET_NAME=ldp-songs

Les 4 primeres variables les usa el backend (Spring Boot). ACRCLOUD_BUCKET_NAME l'usa l'script de sincronització.

Verificació

1. Arrenca el backend amb el perfil local
2. Als logs hauries de veure que ACRCloudClient s'activa
3. L'endpoint POST /api/music/identify hauria d'estar disponible

Sincronitzar fingerprints

Un cop el backend funciona i tens cançons amb preview_url, puja les fingerprints al bucket:

# Dry-run primer (mostra què farà sense fer-ho)
python scripts/etl/sync_fingerprints_acrcloud.py --dry-run --limit 10

# Sync de les primeres 100 cançons
python scripts/etl/sync_fingerprints_acrcloud.py --limit 100

# Sync complet (totes les cançons amb preview)
python scripts/etl/sync_fingerprints_acrcloud.py

L'script:

1. Busca cançons amb preview_url que encara no s'han sincronitzat (acrcloud_synced_at IS NULL)
2. Descarrega el preview de 30 segons
3. Puja la fingerprint al bucket ldp-songs amb metadades (song_id, title, artist, ISRC)
4. Guarda acrcloud_acr_id i acrcloud_synced_at a la BD

Limitacions i quotes

Pla	Durada	Requests
Trial	14 dies	Il·limitat
Starter	Mensual	500/dia
Standard	Mensual	~8.000/mes

Per un MVP/proves, el trial de 14 dies és suficient.

Resolució de problemes

Error 3001 (Missing/invalid Access Key)

• Verifica que ACRCLOUD_ACCESS_KEY és correcte al .env
• Verifica que el backend ha carregat les variables (perfil local)

Error 3003 (Limit exceeded)

• Has superat la quota del teu pla
• Verifica al dashboard d'ACRCloud el consum

Error 3015 (No result)

• Normal si la cançó no està al teu bucket custom
• Assegura't d'haver executat sync_fingerprints_acrcloud.py prèviament

El backend no detecta ACRCloud

• Verifica que ACRCLOUD_ENABLED=true al .env
• Verifica que el perfil local està actiu (application-local.yml)