Bautoven

Bautoven e' un tool locale per Linux che usa SongRec per riconoscere file musicali, aggiorna i tag e organizza la libreria nel formato Artista/Album/Titolo + estensione originale del file.

Requisiti

• Python 3.10+
• SongRec disponibile nel PATH come songrec
• Chromaprint disponibile come fpcalc per il fallback opzionale AcoustID
• ffmpeg consigliato per migliorare il supporto ai formati di SongRec

Installazione rapida

Lo script seguente rileva Arch Linux, Ubuntu e Fedora, installa le dipendenze note, prepara un virtualenv locale e crea il launcher globale bautoven in /usr/local/bin:

./install.sh

Se vuoi ricreare da zero l'installazione locale, per esempio per passare da una variante all'altra, usa:

./install.sh --repair

Per installare direttamente anche il supporto opzionale alla conversione giapponese:

./install.sh --with-japanese

Per ricreare da zero l'ambiente includendo anche il supporto giapponese:

./install.sh --repair --with-japanese

Se il virtualenv esiste gia' e vuoi aggiungere solo quelle dipendenze:

./.venv/bin/pip install -e '.[japanese]'

Per rimuovere l'installazione locale del progetto:

./install.sh --uninstall

--uninstall rimuove il virtualenv locale, il launcher globale in /usr/local/bin/bautoven e i metadata editable del progetto, ma non disinstalla automaticamente SongRec, ffmpeg o altri pacchetti di sistema.

Uso

bautoven /percorso/input /percorso/output --dry-run

Opzioni principali:

• --dry-run: non modifica file, tag o directory
• --log-file /percorso/file.log: salva una copia aggiuntiva del log nel percorso indicato
• --rebuild-library: riconosce nuovamente e riorganizza una libreria esistente
• --no-recognition: riorganizza i file usando solo i tag gia' presenti senza chiamare SongRec
• --progress-file /percorso/stato.txt: file di stato per riprendere l'elaborazione
• --overwrite: se la destinazione esiste gia', la sovrascrive invece di skippare il file
• --songrec-timeout 90: limite massimo in secondi per il riconoscimento di un singolo file
• --songrec-retries 3: numero massimo di retry per file in caso di errore o timeout di SongRec
• --max-consecutive-skips 3: interrompe tutto se troppe canzoni vengono skippate di seguito per errore
• --enable-japanese-reading: attiva la conversione giapponese per la singola esecuzione
• --disable-japanese-reading: disattiva la conversione giapponese per la singola esecuzione
• --extensions .mp3: limita o estende le estensioni scandite

Equivalenze degli artisti

Per ricondurre vari nomi dello stesso artista a un unico nome canonico, modifica il file config.json nella directory principale di Bautoven. Il file viene caricato automaticamente e non deve essere passato sulla riga di comando. Il formato e':

{
  "equivalenze": {
    "J.A.X.": ["JAX", "Articolo 31", "J A X"]
  }
}

La chiave e' il nome che verra' scritto nei tag e usato nella directory di destinazione. Ogni elemento della lista e' un alias distinto; il nome canonico viene riconosciuto automaticamente. Il confronto ignora maiuscole/minuscole e spazi ripetuti, ma conserva la punteggiatura per evitare corrispondenze accidentali.

Destinazione per singolo brano

La sezione track_routes assegna un singolo brano a una cartella-artista virtuale senza modificare il tag ARTIST del file:

{
  "track_routes": {
    "Sword Art Online": [
      {"title": "INNOCENCE", "artist": "Eir Aoi"}
    ]
  }
}

Il confronto di titolo e artista e' esatto ma ignora maiuscole/minuscole, differenze di normalizzazione Unicode e spazi ripetuti. artist puo' essere omesso, ma e' consigliato per evitare collisioni fra canzoni omonime. Se la destinazione virtuale compare anche in prefix, il brano ne eredita il prefisso: l'esempio configurato produce quindi JMusic/Sword Art Online/Album/INNOCENCE.mp3, lasciando Eir Aoi nei tag.

Impostazioni predefinite

La sezione defaults di config.json controlla le impostazioni usate quando la CLI non specifica diversamente:

{
  "defaults": {
    "japanese_reading": true,
    "transliterate_cyrillic": true,
    "repair_encoding": true,
    "unrecognized_folder": "Non Riconosciute"
  }
}

japanese_reading abilita la conversione in katakana. La CLI puo' sovrascrivere questo valore con --enable-japanese-reading o --disable-japanese-reading. unrecognized_folder stabilisce il nome della cartella in cui vengono spostati i brani non riconosciuti durante il catalogamento normale.

transliterate_cyrillic converte esclusivamente il testo cirillico in caratteri latini. repair_encoding tenta una correzione conservativa delle sequenze tipiche di mojibake, senza rimuovere accenti latini o trasformare genericamente Unicode in ASCII. Se dopo questi passaggi rimangono caratteri alfabetici non gestiti, il testo viene conservato e il file compare nella sezione Warning Unicode non risolti del riepilogo e del log.

Fallback AcoustID

Se SongRec non riconosce un brano, Bautoven puo' calcolarne il fingerprint con Chromaprint e cercarlo su AcoustID/MusicBrainz. Registra gratuitamente un'applicazione sul sito AcoustID e inserisci la relativa chiave client in config.json:

{
  "recognition": {
    "acoustid": {
      "api_key": "LA_TUA_CHIAVE",
      "min_score": 0.8
    }
  }
}

Con una chiave vuota il fallback viene saltato senza bloccare l'esecuzione. min_score accetta valori tra 0 e 1 e impedisce di usare risultati troppo incerti. Il log indica per ogni riconoscimento se i metadati provengono da SongRec/Shazam o AcoustID/MusicBrainz.

Lo stesso file permette di raggruppare alcuni artisti sotto una cartella prefisso:

{
  "prefix": {
    "JMusic": ["LiSA", "UVERworld", "YOASOBI"]
  }
}

In questo esempio un brano di LiSA viene collocato in JMusic/LiSA/Album/Titolo.mp3. Le equivalenze vengono applicate prima della ricerca del prefisso.

Se non passi input_dir e output_dir, Bautoven li chiede interattivamente in console.

Ogni esecuzione crea automaticamente un file di log in /tmp, mostrandone il percorso all'avvio e nel riepilogo finale. --log-file permette di conservarne anche una seconda copia.

Ricostruzione completa della libreria

Per rianalizzare e riorganizzare da capo una libreria esistente:

bautoven /percorso/libreria --rebuild-library

In questa modalita' la directory di input e' anche quella di destinazione. Bautoven crea prima in /tmp un manifesto JSON con tutti i percorsi originali, poi riconosce nuovamente i file MP3, M4A, FLAC e OGG. Sposta e aggiorna soltanto i brani riconosciuti con successo; quelli non riconosciuti o che producono un errore rimangono nella posizione originale. Il manifesto viene aggiornato dopo ogni file con stato e destinazione finale. Al termine vengono eliminate, dal livello piu' profondo verso l'alto, soltanto le directory rimaste completamente vuote. Con --dry-run vengono solamente elencate nel log.

Per simulare l'operazione mantenendo comunque log e manifesto diagnostico:

bautoven /percorso/libreria --rebuild-library --dry-run

Con --no-recognition, Bautoven non prova a identificare i brani: legge i tag del file e lo ricolloca direttamente in Artista/Album/Titolo.ext, usando i fallback standard quando qualche campo manca.

Se usi --enable-japanese-reading senza avere installato l'extra opzionale, il tool si ferma con un messaggio che indica il comando di installazione corretto.

Se SongRec si blocca su un file problematico, Bautoven interrompe solo quel tentativo dopo il timeout configurato e continua con il file successivo.

Se un file va in errore o timeout, Bautoven ritenta fino a 3 volte per default; se anche dopo i retry quel file viene skippato, e questo succede per 3 canzoni consecutive, l'intero script si interrompe.

Se la destinazione contiene gia' lo stesso file finale, Bautoven lo skippa per default. Con --overwrite usa invece quel path e sostituisce il file esistente.

Durante l'esecuzione Bautoven aggiorna un file di stato, per default Output/.bautoven-progress.txt, con righe nel formato "sorgente" "destinazione" stato. Lo stato passa prima a processing e poi a valori finali come ok, not-found o skip-existing, cosi' una nuova esecuzione puo' riprendere senza rifare i file gia' completati.

Se /usr/local/bin non e' gia' nel tuo PATH, lo script di installazione te lo segnala: in quel caso il launcher viene creato comunque, ma devi aggiungere quel percorso alla configurazione della shell per poter invocare bautoven senza path assoluto.

Note operative

• Il tool elabora ricorsivamente la directory di input.
• Titolo.ext e' una notazione generica: per esempio un file MP3 riconosciuto diventa Artista/Album/Titolo.mp3, mantenendo l'estensione originale.
• I file non riconosciuti vengono spostati nella cartella configurata, per default Non Riconosciute/, senza modificare i metadati.
• Le collisioni sono gestite con suffissi del tipo Titolo (2).mp3.
• Attualmente la scrittura dei tag e' implementata per MP3, ma la struttura del codice e' pronta per estensioni future.
• Se il riconoscimento via songrec recognize --json non e' supportato dalla versione installata, il tool prova automaticamente songrec audio-file-to-recognized-song.