[TUTO] Installer STUdio 0.4.2 et Lunii.QT sur macOS 27 avec une Lunii V3

[immobilis-mobile]

Bonjour,
Voici un retour d’expérience pour faire fonctionner STUdio 0.4.2 et Lunii.QT 3.1.4 sous macOS 27, sur un Mac Apple Silicon, avec une Fabrique à Histoires Lunii V3.
Ces outils sont communautaires, non officiels et sans garantie. Faites une sauvegarde avant toute modification et n’ouvrez jamais plusieurs applications Lunii simultanément.
Outils installés
Application officielle Lunii
Lunii.QT
STUdio 0.4.2
FFmpeg pour la conversion audio
Rosetta 2
Temurin JDK 11 Intel x86-64

1. Installer l’application officielle Lunii

Installez d’abord l’application officielle. Elle permet notamment :
d’associer la Fabrique au compte Lunii ;
d’installer le firmware officiel ;
de vérifier que le câble USB et la connexion fonctionnent ;
de synchroniser les livres achetés.
Avec une Lunii V3, utilisez le câble USB-C Lunii ou un câble compatible avec le transfert de données.

2. Installer Lunii.QT

Téléchargez la dernière version macOS depuis :
https://github.com/o-daneel/Lunii.QT/releases
Ouvrez le DMG et copiez luniiQt.app dans Applications.
Comme l’application n’est pas notariée par Apple, macOS peut afficher :
« luniiQt.app est endommagé et ne peut pas être ouvert »

Si le fichier provient bien du dépôt officiel, ouvrez Terminal et exécutez :
xattr -dr com.apple.quarantine "/Applications/luniiQt.app"
Ensuite :
Faites un clic droit sur luniiQt.app.
Choisissez Ouvrir.
Confirmez l’ouverture.
Autre possibilité :
Essayez d’ouvrir l’application une première fois.
Allez dans Réglages Système → Confidentialité et sécurité.
Dans la partie Sécurité, cliquez sur Ouvrir quand même.
Autoriser l’accès à la Lunii
Sous macOS 27, Lunii.QT peut afficher No Lunii detected alors que l’application officielle voit correctement l’appareil.
Vérifiez :
Réglages Système → Confidentialité et sécurité → Fichiers et dossiers → luniiQt
Activez Volumes amovibles.
Si cette option n’apparaît pas, ajoutez /Applications/luniiQt.app à Accès complet au disque, puis relancez l’application.
Pour vérifier que macOS a monté la Fabrique :
ls -la "/Volumes/LUNII"
Sur ma V3, le volume contient notamment :
.md
.pi
.cfg
.content
st
etc
version
Si ces éléments sont visibles, le câble et le montage fonctionnent : le problème vient alors probablement des autorisations de Lunii.QT ou d’un conflit avec une autre application.
Installer FFmpeg dans Lunii.QT
FFmpeg est nécessaire pour transcoder certains fichiers audio contenus dans les packs.
Dans Lunii.QT :
Ouvrez le menu Outils.
Sélectionnez FFMPEG absent.
Laissez l’application effectuer le téléchargement.
Vérifiez ensuite que le menu indique FFMPEG détecté.
Le fichier est normalement placé dans :
~/.lunii-qt/ffmpeg

3. Installer STUdio 0.4.2

Téléchargez et décompressez la version 0.4.2 :
https://github.com/marian-m12l/studio/releases
Cette version prend en charge :
la Lunii V3 ;
le firmware 3.2.2 et suivants ;
les métadonnées V7.
Cependant, le paquet macOS ne contient que la bibliothèque USB native Intel :
libusb4java-1.3.0-darwin-x86-64.jar
Sur un Mac Apple Silicon avec un Java ARM, STUdio échoue avec :
Native library not found in classpath:
/org/usb4java/darwin-aarch64/libusb4java.dylib
Il faut donc exécuter STUdio entièrement en mode Intel grâce à Rosetta et un JDK Intel.

4. Installer Rosetta 2

Dans Terminal :
softwareupdate --install-rosetta --agree-to-license
On peut vérifier son fonctionnement avec :
arch -x86_64 /usr/bin/true
L’absence de message d’erreur indique normalement que Rosetta fonctionne.

5. Installer un JDK 11 Intel

Attention : le programme d’installation Oracle JDK x64 peut refuser de s’installer sur un Mac ARM avec ce message :
This installation of JDK is for x64 systems. On this computer please download the arm 64 installer.

Il ne faut pourtant pas utiliser la version ARM pour STUdio, car elle ne peut pas charger la bibliothèque USB Intel.
La solution consiste à télécharger une archive TAR.GZ, sans installateur, de Temurin :
https://adoptium.net/temurin/releases/
Choisissez :
version : JDK 11 ;
système : macOS ;
architecture : x64 ;
format : TAR.GZ.
Décompressez-la dans :
~/Library/Java/JavaVirtualMachines/
Dans mon cas, le chemin obtenu était :
~/Library/Java/JavaVirtualMachines/jdk-11.0.32+9/
Vérification :
file "$HOME/Library/Java/JavaVirtualMachines/jdk-11.0.32+9/Contents/Home/bin/java"
Le résultat doit contenir :
Mach-O 64-bit executable x86_64
Test sous Rosetta :
arch -x86_64
"$HOME/Library/Java/JavaVirtualMachines/jdk-11.0.32+9/Contents/Home/bin/java"
-version

6. Lancer correctement STUdio

Ne lancez pas directement le JAR avec java -jar. Le fichier ne possède pas de classe principale dans son manifeste et macOS répondrait :
aucun attribut manifest principal
Il faut utiliser le script studio-macos.sh livré dans l’archive, avec le Java Intel placé en tête du PATH.
Adaptez les chemins si nécessaire :
cd "$HOME/Downloads/studio-web-ui-0.4.2"

env PATH="$HOME/Library/Java/JavaVirtualMachines/jdk-11.0.32+9/Contents/Home/bin:/usr/bin:/bin:/usr/sbin:/sbin"
/bin/sh "./studio-macos.sh"
Lorsque tout fonctionne, le journal affiche notamment :
Initializing libusb...
Hotplug is supported.
Succeeded in deploying verticle
L’interface doit ensuite s’ouvrir automatiquement. Sinon, ouvrez :
http://localhost:8080/
Laissez la fenêtre Terminal ouverte pendant l’utilisation.

7. Brancher et détecter la Lunii V3

Pour éviter les conflits :
Fermez l’application officielle Lunii avec ⌘Q.
Fermez Lunii.QT.
Arrêtez STUdio s’il est encore actif.
Éteignez puis débranchez la Fabrique.
Attendez quelques secondes.
Rebranchez-la directement au Mac.
Allumez-la et acceptez la connexion.
Lancez uniquement l’outil que vous souhaitez utiliser.
Un logo USB affiché sur la Fabrique confirme qu’elle est connectée, mais pas forcément que macOS l’a montée.
Pour contrôler la détection USB :
ioreg -p IOUSB -l -w 0 | grep -i -A 15 -B 5 "Lunii"
Pour contrôler le montage :
ls -la "/Volumes/LUNII"
Dans Lunii.QT, appuyez sur F5 pour relancer la détection.

8. Créer ou importer un pack

Un MP3 seul n’est pas une histoire Lunii complète. Il faut créer un pack contenant :
un titre et des métadonnées ;
une image ;
un ou plusieurs fichiers audio ;
une structure de navigation ;
un début et une fin ou un retour au menu.
STUdio permet de créer ce pack. Les formats audio acceptés comprennent notamment MP3, OGG et WAV.
Pour préparer manuellement un MP3 compatible :
ffmpeg -i "histoire-originale.mp3"
-ar 44100
-ac 1
-codec:a libmp3lame
-b:a 128k
"histoire-lunii.mp3"
Lunii.QT sait transcoder l’audio d’un pack grâce à FFmpeg, mais ne transforme pas automatiquement un MP3 isolé en histoire complète.
Lunii.QT accepte notamment :
.plain.pk ;
.pk, .v1.pk et .v2.pk ;
certaines archives .zip et .7z ;
les archives compatibles avec STUdio.
Le format .plain.pk est généralement préférable, car l’audio est déjà compatible et l’importation évite un long transcodage.

9. Importer avec Lunii.QT

Fermez Lunii et STUdio.
Branchez et allumez la V3.
Ouvrez Lunii.QT.
Attendez que l’appareil soit détecté.
Utilisez Fichier → Importer ou Ctrl+I.
Sélectionnez le pack.
Attendez la fin complète de l’écriture.
Éjectez proprement la Fabrique avant de la débrancher.
Avant de synchroniser ensuite avec l’application officielle, utilisez la fonction Masquer de Lunii.QT pour vos packs personnels. Dans le cas contraire, l’application officielle peut supprimer les histoires tierces pendant la synchronisation.
Problèmes rencontrés et solutions
sun.misc.Unsafe est déprécié
WARNING: A terminally deprecated method in sun.misc.Unsafe has been called
Ce n’était qu’un avertissement provenant d’une ancienne version de Netty. Il n’empêchait pas STUdio de démarrer.
official.json est absent
Missing official metadata database file
FileNotFoundException: ~/.studio/db/official.json
Au premier démarrage, STUdio a ensuite téléchargé automatiquement la base :
Fetched metadata, updating local database
Ce message n’était donc pas bloquant.
Bibliothèque darwin-aarch64 introuvable
Native library not found in classpath:
/org/usb4java/darwin-aarch64/libusb4java.dylib
C’était le véritable blocage. Solution : Rosetta + JDK 11 Intel x86-64.
No Lunii detected
Si l’application officielle détecte la Fabrique mais pas Lunii.QT :
éjecter la Lunii depuis l’application officielle ;
quitter celle-ci avec ⌘Q ;
fermer STUdio ;
reconnecter la Fabrique ;
autoriser Lunii.QT à accéder aux volumes amovibles ;
relancer Lunii.QT et appuyer sur F5.
Avertissements
STUdio et Lunii.QT ne sont pas affiliés à Lunii.
La prise en charge V3 est communautaire et peut présenter des risques.
Conservez une sauvegarde de vos créations et, si possible, du firmware.
Ne formatez pas la Lunii pour un simple problème de détection.
N’exécutez pas STUdio en administrateur.
Ne lancez jamais Lunii, Lunii.QT et STUdio simultanément.
Utilisez uniquement des contenus personnels, libres ou dont vous possédez les droits.
Rosetta reste disponible sous macOS 27, mais ce montage dépend d’un composant Intel ancien ; une version ARM native serait préférable à long terme.
En résumé, tout fonctionne sous macOS 27, mais STUdio 0.4.2 doit être lancé avec Rosetta et un JDK 11 Intel, tandis que Lunii.QT nécessite parfois une autorisation explicite d’accès aux volumes amovibles.