Documentation

Installation, chemins de données, configuration, réseau, API et dépannage. Tout ce qui tourne sur ta machine, expliqué.

1. Installation par plateforme

Un exécutable par système. Le runtime est inclus.

AppImage (Linux)

Publié

glibc 2.31 ou plus récent. Un fichier unique, rendu exécutable. Le runtime Python, llama.cpp et le moteur audio sont inclus dedans.

Installateur (Windows)

Publié

Windows 10 ou 11, 64 bits. Installateur classique : le dossier de données est conservé entre les versions.

APK (Android)

Publié

Android 10 ou plus récent, 4 architectures CPU. Signé avec la clé de distribution du projet, ce qui lui permet de se mettre à jour tout seul : Android refuse d'installer un paquet signé par une autre clé que celle de l'application déjà installée.

Prérequis matériels

6 Go de RAM pour charger le plus petit modèle d'IA. Le lecteur audio fonctionne avec moins.
Autant d'espace disque que la taille du modèle, plus 300 Mio de marge.
Un GPU accélère le calcul s'il est compatible Vulkan. Sans accélération, tout se fait sur le processeur, plus lentement.

2. Où sont mes données ?

L'application écrit dans un dossier, et nulle part ailleurs.

L'application de bureau utilise un dossier principal et un sous-dossier de données, tous deux dans ton dossier utilisateur. Ces chemins valent pour l'AppImage publiée.

Interface, réglages et modèles

Linux    ~/.config/NeuroBeats
Windows  %APPDATA%\NeuroBeats

Les réglages de l'application et son journal. Les modèles téléchargés vont dans un sous-dossier models.

Historique et caches

Linux    ~/.config/NeuroBeats/data
Windows  %APPDATA%\NeuroBeats\data

La base SQLite, l'historique, les notes, les favoris et les caches. C'est ce dossier-là qu'il faut supprimer pour repartir de zéro.

Si tu lances le moteur seul ces chemins ne s'appliquent pas. Sans variable d'environnement, le moteur écrit dans un dossier par profil, en minuscules : ~/.local/share/neurobeats/<profil> sous Linux. Le profil vaut web par défaut, et desktop pour l'application.

Pour une désinstallation complète ferme l'application, supprime son dossier de données, puis l'exécutable. Les deux chemins ci-dessus contiennent tout ce que l'application a écrit.

3. Variables d'environnement

Elles servent aux cas particuliers. L'application de bureau les fixe toute seule.

Une variable d'environnement est une valeur que tu définis avant de lancer un programme. NeuroBeats en lit six. Dans l'application de bureau, tu n'as rien à faire : elle les affecte toutes à chaque démarrage. Elles comptent surtout si tu lances le moteur seul, ou si tu veux faire cohabiter deux instances.

NEUROBEATS_PORTPort

8000

Port du moteur local. L'application de bureau le fixe à 8041, le développement web utilise 8040.

NEUROBEATS_DATA_DIRStockage

selon le système

Historique, notes, favoris, caches et base SQLite. Sans valeur, le chemin dépend du système et du profil.

NEUROBEATS_MODELS_DIRStockage

selon le système

Fichiers GGUF téléchargés. Sans valeur, il suit le même schéma que les données, avec un sous-dossier models.

NEUROBEATS_PROFILEProfil

web

Nom du sous-dossier de données. L'application de bureau force desktop. Deux profils ne partagent rien.

NEUROBEATS_FRONTEND_PORTPort

3150

Port de l'interface web embarquée, quand elle est servie séparément du moteur.

NEUROBEATS_LYRICS_MISS_TTL_DAYSCache

Durée de mise en cache d'une recherche de paroles sans résultat. Un résultat réussi est gardé 30 jours.

À propos du port 8041 dans l'application de bureau, 8040 en développement web, 8000 par défaut si tu lances le moteur seul. C'est le port du moteur, pas celui de l'interface.

4. Modèles d'IA

Tu choisis le fichier de poids qui fait tourner l'assistant.

Un modèle d'IA est un fichier de poids, au format GGUF. GGUF est le format lu par llama.cpp, le moteur qui l'exécute sur ta machine. L'application n'en fournit aucun : tu télécharges celui que tu veux.

Choisir dans le catalogue

Ouvre Profil puis IA. Le catalogue liste sept modèles par défaut, avec leur taille et la mémoire qu'ils demandent. Lance le téléchargement depuis cette page. Ce catalogue est une sélection, pas une limite : la même page permet de chercher n'importe quel dépôt GGUF du Hub, et les fichiers y sont filtrés sur ce que ta machine peut réellement charger.

Tu dois voir le modèle apparaître dans la liste des modèles téléchargés, et son état passer à « prêt ».

Choisir un modèle hors catalogue

Dans la même page, « Parcourir Hugging Face » ouvre le Hub et cherche n'importe quel dépôt GGUF. Un modèle trouvé ainsi se télécharge exactement comme un modèle du catalogue.

Tu dois voir la taille du fichier avant de lancer, et l'espace disque est vérifié avant le téléchargement.

Utiliser un moteur déjà installé

Si tu as déjà Ollama ou LM Studio, pointe NeuroBeats dessus dans les mêmes réglages. Tu peux aussi donner une clé OpenAI ou Anthropic. Dans ce dernier cas, tes questions partent chez ce fournisseur, et l'assistant cesse d'être entièrement local.

Tu dois voir le bouton « Tester la connexion » confirmer que le moteur répond.

Aucun modèle n'est audité par NeuroBeats le catalogue est une sélection de notre part, pas un audit. Chaque modèle reste la propriété de son auteur : cinq des sept sont en Apache-2.0, un sous licence Llama-3.1, un sous licence Gemma. Lis les conditions de chaque auteur avant toute redistribution.

5. API locale

Le moteur expose une API HTTP, pour le piloter à la main.

Une API est une interface qui permet à un autre programme de demander des choses au moteur. NeuroBeats en expose une, de plus de quatre-vingts routes. Voici les principales.

Tu dois voir une commande comme curl http://127.0.0.1:8041/api/now renvoie le titre en cours au format JSON. Le port 8041 vaut pour l'application de bureau : remplace-le par celui de ton lancement.

Lecture

GET/api/now

Le titre en cours et sa position.

POST/api/play

Ajoute un titre à la file.

POST/api/play_now

Lecture immédiate : la file est remplacée.

POST/api/stop

Arrête la lecture.

POST/api/pause

Bascule pause ou reprise.

POST/api/seek

Déplace la tête de lecture.

POST/api/volume

Règle le volume.

GET/api/audio/{id}

Diffuse l'audio d'un titre.

Flux infini

POST/api/stream/start

Démarre le flux et remplit la file.

POST/api/stream/stop

Arrête le flux.

POST/api/stream/skip

Passe au titre suivant.

GET/api/stream/queue

File et titres à venir.

Recommandation

GET/api/recommend

Titres recommandés pour une ambiance, en tenant compte de l'historique.

GET/api/discover

Sélection par genre.

GET/api/search

Recherche de titres et d'artistes.

Playlists

GET/api/playlists

Liste des playlists.

POST/api/playlists

Crée une playlist.

POST/api/playlists/{id}/tracks

Ajoute un titre.

DELETE/api/playlists/{id}

Supprime une playlist.

Profil et données

GET/api/profile/ai

Réglages IA, modèles téléchargés, état du moteur.

GET/api/profile/history

Historique d'écoute.

DELETE/api/profile/history

Efface l'historique. Exige ?confirm=1 en paramètre. Les notes et favoris restent.

POST/api/profile/caches/clear

Vide les caches. Ils se reconstruisent seuls.

GET/api/stats

Statistiques d'écoute.

GET/api/lyrics

Paroles synchronisées ou texte brut.

Chat

POST/api/chat

Une question à l'assistant, avec appel d'outils si nécessaire.

POST/api/chat/stream

La même chose, réponse en flux.

Divers

GET/api/health

État du moteur et identité de l'instance.

GET/api/home

Chargement initial de l'écran d'accueil.

POST/api/preference

Enregistre la note d'un titre. C'est ce qui nourrit le classement.

POST/api/transfer

Crée la session de transfert affichée en QR code.

Deux exceptions à la règle /api le temps réel passe par une connexion WebSocket sur /ws, et le transfert vers le téléphone par des routes /t/… qui ne sont pas sous /api. Les accolades des routes ci-dessus sont des paramètres : remplace-les par l'identifiant réel.

6. Ce que l'application va chercher sur le réseau

La liste exacte, y compris ce qui part sans que tu le demandes.

Ton historique, tes notes et tes favoris ne quittent jamais ta machine : il n'existe aucun serveur NeuroBeats vers lequel ils pourraient partir. En revanche, l'application va chercher des choses en ligne, comme tout lecteur de musique.

YouTube

Métadonnées des titres et flux audio, via yt-dlp.

À chaque recherche et à chaque titre joué, sauf si le titre est déjà en cache.

LRCLIB, puis Genius

Paroles. LRCLIB fournit des paroles synchronisées, Genius du texte brut.

À la première recherche d'un titre, puis servi depuis le cache.

Deezer et i.ytimg.com

Pochettes d'albums.

À la première consultation, puis servi depuis le disque.

Hugging Face

Recherche de dépôts GGUF et téléchargement des modèles.

Quand tu Parcouris le Hub ou télécharges un modèle.

PyPI

Mise à jour du module yt-dlp, le récupérateur d'audio du client Android.

Seulement après un échec réseau pendant un téléchargement sur Android.

hetzner.com

Sonde de bande passante : elle télécharge 10 Mio pour choisir un niveau de qualité audio.

Une fois, à chaque lancement, sans action de ta part.

Deux requêtes que tu ne déclenches pas au démarrage, l'application de bureau télécharge 10 Mio depuis hetzner.com pour mesurer ton débit, sans te prévenir. Sur Android, un échec réseau lors d'un téléchargement déclenche une mise à jour du module yt-dlp depuis PyPI. Dans les deux cas, l'adresse est identifiante.

Ce qui marche sans réseau

L'assistant, une fois un modèle chargé : il tourne dans llama.cpp, sur ta machine.
Le classement, les statistiques, et les paroles déjà mises en cache.
Les titres déjà téléchargés ou gardés en mémoire : ils se rejouent sans réseau.

Ce qui demande le réseau : un titre jamais joué, une recherche, et des paroles jamais trouvées. Sans réseau, la recommandation se limite aux titres de ton historique.

7. Dépannage

Trois incidents courants, et où lire les détails.

Le moteur ne démarre pas

Un autre processus occupe déjà le port. Relance avec un autre NEUROBEATS_PORT, ou ferme le processus qui occupe le port.

Un modèle ne se charge pas

L'application n'interdit aucun modèle : elle signale ceux qui dépassent ta mémoire. Si le chargement échoue quand même, le fichier est peut-être corrompu. Supprime-le et retélécharge-le.

Aucune recommandation

La première construction prend quelques dizaines de secondes. L'interface affiche des squelettes pendant ce temps. Sans réseau, les recommandations se limitent aux titres déjà écoutés.

Lire le journal

L'application écrit ce qu'elle fait dans un journal, à côté de ses réglages. Il contient les appels d'outils de l'assistant, les scores de recommandation et les erreurs du moteur. C'est le meilleur point de départ pour comprendre un problème.

Tu dois voir la ligne qui correspond à ton problème, avec l'heure.

Ferme l'application normalement elle arrête le moteur audio et libère le port. Une fermeture brutale peut laisser un processus en cours, qui refusera ensuite de démarrer.