================================================================================
 NOTICE D'INSTALLATION ET D'UTILISATION
 wav2x7000qd_fixed.py — Convertisseur WAV -> QD / MIDI SDS pour AKAI X7000
================================================================================
 Document rédigé pour Windows 11, Windows XP, Linux et macOS.
 Dernière mise à jour : session du 2026-07-13.
================================================================================


--------------------------------------------------------------------------------
0. CE DONT TU AS BESOIN AVANT DE COMMENCER
--------------------------------------------------------------------------------

Matériel :
  - Un ordinateur (Windows 11, Windows XP, Linux ou macOS)
  - Pour le CHEMIN A (disque QD)  : un émulateur Gotek avec firmware HxC,
    une clé USB, et bien sûr le X7000/S700/S612
  - Pour le CHEMIN B (MIDI push)  : une interface/câble MIDI reliant
    l'ordinateur au X7000 (port MIDI IN du sampleur)

Fichier logiciel :
  - wav2x7000qd_fixed.py (le script fourni dans le projet)

Format audio source attendu :
  - Fichiers WAV 16 bits mono (c'est le format par défaut exporté par ton DAW).
    Le script sait aussi lire du 8/16/24/32 bits, mono ou stéréo, mais tu n'as
    normalement rien à changer si tu exportes toujours en 16 bits mono.


--------------------------------------------------------------------------------
1. VUE D'ENSEMBLE — QUE FAIT LE SCRIPT ?
--------------------------------------------------------------------------------

Le script propose une interface graphique (fenêtre) avec deux usages
indépendants :

  CHEMIN A — Conversion WAV -> fichier .QD à copier sur la clé USB du Gotek
             (aucune connexion MIDI nécessaire, juste un port USB pour
             transférer le fichier vers la clé du Gotek)

  CHEMIN B — Envoi direct d'un WAV vers le X7000 par câble MIDI, sans disque
             (nécessite une interface MIDI et le câble)

Le script est écrit en Python 3. Il a besoin :
  - de Python 3 installé sur la machine (OBLIGATOIRE)
  - du module Tkinter pour l'interface graphique (généralement inclus avec
    Python, mais pas toujours sur Linux — voir plus bas)
  - de numpy (FACULTATIF — améliore la qualité du rééchantillonnage audio,
    le script fonctionne sans, avec une qualité légèrement inférieure)
  - de python-rtmidi (FACULTATIF, mais OBLIGATOIRE si tu veux utiliser le
    Chemin B — MIDI. Pas nécessaire pour le Chemin A — QD seul)


--------------------------------------------------------------------------------
2. INSTALLATION — WINDOWS 11
--------------------------------------------------------------------------------

Étape 1 — Installer Python
  1. Va sur https://www.python.org/downloads/
  2. Télécharge la dernière version stable de Python 3 (ex. Python 3.12)
  3. Lance l'installeur téléchargé
  4. IMPORTANT : coche la case "Add python.exe to PATH" en bas de la
     première fenêtre d'installation avant de cliquer sur "Install Now"
  5. Laisse l'installation se terminer, puis ferme l'installeur

  Alternative rapide : ouvrir le Microsoft Store, chercher "Python 3.12"
  (ou la version la plus récente proposée) et cliquer sur "Installer".

Étape 2 — Vérifier l'installation
  1. Ouvre le menu Démarrer, tape "cmd" et lance "Invite de commandes"
  2. Tape la commande suivante puis Entrée :
         python --version
     Tu dois voir s'afficher quelque chose comme "Python 3.12.x"
     (si "python" n'est pas reconnu, redémarre l'ordinateur une fois —
     parfois nécessaire pour que le PATH soit pris en compte)

Étape 3 — Installer les dépendances facultatives
  Dans la même invite de commandes, tape :
         python -m pip install --upgrade pip
         python -m pip install numpy
  Puis, uniquement si tu veux utiliser le Chemin B (MIDI) :
         python -m pip install python-rtmidi

Étape 4 — Lancer le script
  Deux méthodes :
  a) Double-clique directement sur le fichier wav2x7000qd_fixed.py
     (si l'association de fichier .py à Python est active, la fenêtre du
     programme s'ouvre directement)
  b) Ou, plus fiable : ouvre l'invite de commandes, place-toi dans le
     dossier contenant le script avec la commande "cd", par exemple :
         cd C:\Users\TonNom\Downloads
     puis lance :
         python wav2x7000qd_fixed.py

Windows 11 : Tkinter est inclus automatiquement avec l'installeur officiel
python.org, aucune action supplémentaire requise.


--------------------------------------------------------------------------------
3. INSTALLATION — WINDOWS XP
--------------------------------------------------------------------------------

  ATTENTION — LIMITATION TECHNIQUE IMPORTANTE, À LIRE AVANT TOUT :

  Le script utilise des fonctionnalités du langage (f-strings) qui exigent
  au minimum Python 3.6. Or la DERNIÈRE version officielle de Python
  compatible avec Windows XP est Python 3.4.4 (sortie en 2015). Le script
  NE PEUT DONC PAS fonctionner tel quel sur un Windows XP avec une
  installation Python officielle standard.

  Solutions possibles, par ordre de simplicité :

  Option recommandée — Utiliser un autre ordinateur pour le Chemin A
    Le fichier .QD produit par le Chemin A (conversion WAV->QD) n'a besoin
    d'être transféré que sur la clé USB du Gotek : tu peux donc very
    simplement faire la conversion sur un PC Windows 11 / Linux / Mac
    récent, puis copier le fichier .QD résultant sur la clé USB, et
    brancher cette clé sur le Gotek relié au X7000. Le Windows XP n'a alors
    plus besoin de faire tourner Python du tout.

  Option alternative — Machine virtuelle ou Live USB Linux
    Installer sur la machine XP (si le matériel le permet) un logiciel de
    virtualisation léger, ou démarrer sur une clé USB "Live" Linux (ex.
    Linux Mint, Xubuntu) qui n'installe rien sur le disque dur et permet
    de suivre directement la section LINUX de cette notice.

  Option avancée (déconseillée sauf besoin impératif) — Portage manuel
    Il est théoriquement possible de réécrire les quelques lignes du script
    utilisant des f-strings en syntaxe .format() compatible Python 3.4,
    mais cela demande une intervention technique et n'est pas couvert par
    cette notice. Fais-le-moi savoir si tu veux que je prépare une version
    "compatibilité XP" du script.


--------------------------------------------------------------------------------
4. INSTALLATION — LINUX (Ubuntu / Debian / Mint / Fedora, etc.)
--------------------------------------------------------------------------------

La plupart des distributions Linux récentes incluent déjà Python 3.
Vérifie d'abord :
         python3 --version
Si la commande répond avec une version 3.6 ou supérieure, Python est prêt.

Étape 1 — Installer Python 3 et Tkinter (si absents)

  Sur Ubuntu / Debian / Mint (gestionnaire apt) :
         sudo apt update
         sudo apt install python3 python3-pip python3-tk

  Sur Fedora :
         sudo dnf install python3 python3-pip python3-tkinter

  Sur Arch Linux :
         sudo pacman -S python python-pip tk

  NOTE : sur Linux, "python3-tk" (ou équivalent) est SÉPARÉ du paquet
  Python de base et n'est PAS installé automatiquement — c'est l'oubli le
  plus fréquent. Sans lui, la fenêtre de l'interface graphique ne s'ouvrira
  pas et Python affichera une erreur "No module named 'tkinter'".

Étape 2 — Installer les dépendances facultatives
         python3 -m pip install --upgrade pip
         python3 -m pip install numpy

  Pour le Chemin B (MIDI), python-rtmidi a besoin de bibliothèques système
  de développement (ALSA sur Linux). Installe-les d'abord :

  Ubuntu / Debian / Mint :
         sudo apt install libasound2-dev

  Fedora :
         sudo dnf install alsa-lib-devel

  Puis :
         python3 -m pip install python-rtmidi

Étape 3 — Lancer le script
  Ouvre un terminal, place-toi dans le dossier du script, puis :
         python3 wav2x7000qd_fixed.py

  Astuce : pour lancer le script en double-cliquant depuis le gestionnaire
  de fichiers, il faut généralement le rendre exécutable :
         chmod +x wav2x7000qd_fixed.py


--------------------------------------------------------------------------------
5. INSTALLATION — macOS
--------------------------------------------------------------------------------

macOS inclut parfois une vieille version de Python 2 préinstallée (jamais
suffisante) — il faut installer Python 3 séparément.

Méthode recommandée — Installeur officiel python.org
  1. Va sur https://www.python.org/downloads/macos/
  2. Télécharge la dernière version stable de Python 3 pour macOS
  3. Ouvre le fichier .pkg téléchargé et suis l'installeur (Suivant,
     Suivant, Installer)
  4. Cet installeur inclut automatiquement Tkinter — rien de plus à faire
     pour l'interface graphique

Méthode alternative — Homebrew (si tu l'utilises déjà)
         brew install python-tk

Étape 2 — Vérifier l'installation
  Ouvre "Terminal" (Applications > Utilitaires > Terminal), tape :
         python3 --version
  Tu dois voir la version installée s'afficher.

Étape 3 — Installer les dépendances facultatives
         python3 -m pip install --upgrade pip
         python3 -m pip install numpy
  Pour le Chemin B (MIDI) :
         python3 -m pip install python-rtmidi

  Si l'installation de python-rtmidi échoue avec une erreur de compilation,
  installe d'abord les outils de développement Apple (une seule fois) :
         xcode-select --install
  puis relance la commande pip ci-dessus.

Étape 4 — Lancer le script
  Dans le Terminal, place-toi dans le dossier du script puis :
         python3 wav2x7000qd_fixed.py

  macOS peut demander une autorisation d'accès (MIDI, fichiers) au premier
  lancement — accepte les demandes pour que le script fonctionne
  normalement.


--------------------------------------------------------------------------------
6. VÉRIFICATION RAPIDE — CE QUE TU DOIS VOIR
--------------------------------------------------------------------------------

Si tout est correctement installé, le lancement du script doit ouvrir une
fenêtre intitulée :
   "WAV -> QD | AKAI X7000 (correction LSB-first 2026-06-30)"

Avec, dans l'ordre :
  1. Un champ pour choisir le fichier WAV source
  2. Un champ pour choisir le fichier .QD de destination
  3. Un menu de fréquence (Auto ou une valeur fixe)
  4. Deux boutons : "Convertir WAV -> QD" et "QD vierge (silence)"
  5. Un bloc "MIDI (Play Back)" avec sélection des ports IN/OUT
  6. Un bloc "SDS — Dump Request" avec l'envoi WAV par MIDI (push)
  7. Une zone de texte en bas affichant le journal des opérations

Si le bloc MIDI affiche un message orange/rouge du type
"python-rtmidi indisponible", c'est normal si tu n'as pas installé
python-rtmidi (Chemin B non utilisé) — un bouton "Installer rtmidi"
est présent directement dans la fenêtre pour l'installer sans repasser
par le terminal.


--------------------------------------------------------------------------------
7. UTILISATION — CHEMIN A (WAV vers fichier .QD)
--------------------------------------------------------------------------------

  1. Clique sur "..." à côté de "Fichier WAV" et choisis ton fichier
     (16 bits mono recommandé, mais tout format WAV standard fonctionne)
  2. Le champ "Fichier QD" se remplit automatiquement (même nom, .QD) —
     modifiable si besoin via son propre bouton "..."
  3. Laisse "Fréquence" sur "Auto" (recommandé) ou choisis une valeur fixe
     dans la liste (1600 à 40000 Hz)
  4. Clique sur "Convertir WAV -> QD"
  5. Le journal en bas confirme la réussite et rappelle les instructions :
       - Renomme le fichier produit en DSKA0000.QD (ou 0001, 0002, ...)
       - Copie-le sur la clé USB du Gotek
       - Sur le X7000 : sélectionne le slot puis LOAD

  Pour créer un disque silencieux (utile pour "vider" un slot) : bouton
  "QD vierge (silence)".


--------------------------------------------------------------------------------
8. UTILISATION — CHEMIN B (envoi direct par câble MIDI)
--------------------------------------------------------------------------------

  Pré-requis : python-rtmidi installé (voir section correspondant à ton OS)
  et le X7000 relié à l'ordinateur par un câble/interface MIDI.

  1. Dans le bloc "MIDI (Play Back)", clique sur "Rafraîchir" pour lister
     les ports détectés, puis choisis le bon port MIDI IN et MIDI OUT
  2. Dans le bloc "SDS", choisis le numéro de Sample (S1 = 0, S2 = 1, etc.)
  3. Choisis le fichier WAV à envoyer via "..."
  4. Choisis une fréquence (8000 Hz est un bon compromis qualité/durée par
     défaut), un mode (Loop / Alternate), et éventuellement une note cible
     pour la transposition (C3 = pitch d'origine)
  5. Clique sur "Envoyer ce WAV (push MIDI)" et confirme le message
     d'avertissement (le slot choisi sera écrasé)
  6. Le X7000 doit afficher "Receiving smpl" pendant le transfert
  7. Une fois terminé, clique sur le bouton "PB" pour écouter le résultat
     directement depuis l'interface

  Note importante : la résolution audio par ce chemin est de 8 bits (contre
  12 bits pour le Chemin A), c'est une limitation du protocole MIDI push,
  pas un bug — voir le document RESUME_COMPLET_PROJET_2026-07-13.md du
  projet pour le détail technique.


--------------------------------------------------------------------------------
9. DÉPANNAGE — PROBLÈMES COURANTS
--------------------------------------------------------------------------------

"python n'est pas reconnu comme commande" (Windows)
  -> Réinstalle Python en cochant bien "Add python.exe to PATH", ou
     redémarre l'ordinateur après l'installation.

"No module named 'tkinter'" (Linux)
  -> Installe le paquet système tkinter séparément (voir section Linux,
     Étape 1) — ce n'est PAS installable via pip, c'est un paquet système.

"No module named 'numpy'" ou "No module named 'rtmidi'"
  -> Le script fonctionne quand même (numpy et rtmidi sont facultatifs pour
     le Chemin A). Installe-les via pip si tu veux la meilleure qualité de
     rééchantillonnage (numpy) ou le Chemin B (python-rtmidi).

Le bouton "Installer rtmidi" échoue dans l'interface (Windows/macOS/Linux)
  -> Ouvre un terminal/invite de commandes manuellement et tape :
         python -m pip install python-rtmidi        (Windows)
         python3 -m pip install python-rtmidi        (Linux / macOS)
     Lis le message d'erreur affiché : sur Linux il manque souvent
     libasound2-dev (voir section 4), sur macOS les outils de compilation
     Xcode (voir section 5).

Aucun port MIDI détecté
  -> Vérifie que le câble/interface MIDI est bien branché et reconnu par
     le système AVANT de lancer le script, puis clique sur "Rafraîchir"
     dans l'interface. Sous Windows, vérifie aussi que le pilote de
     l'interface MIDI est installé.

Le fichier .QD ne se charge pas sur le Gotek
  -> Vérifie que le nom du fichier respecte bien le format DSKA0000.QD
     (4 chiffres), et que le firmware HxC du Gotek est à jour.


--------------------------------------------------------------------------------
10. PROTOCOLE DE TESTS SUGGÉRÉ (pour valider une installation machine)
--------------------------------------------------------------------------------

  Test 1 — Lancement de l'interface
    Lancer le script -> la fenêtre s'ouvre sans erreur -> OK/KO

  Test 2 — Conversion QD basique
    Convertir un WAV court (quelques secondes, 16 bits mono) en fréquence
    "Auto" -> fichier .QD produit, taille exactement 204 800 octets -> OK/KO

  Test 3 — QD vierge
    Bouton "QD vierge (silence)" -> fichier produit sans erreur -> OK/KO

  Test 4 (si Chemin B utilisé) — Détection MIDI
    "Rafraîchir" dans le bloc MIDI -> au moins un port IN et un port OUT
    apparaissent -> OK/KO

  Test 5 (si Chemin B utilisé) — Dump Request
    Sélectionner un sample existant, "Envoyer Dump Request" -> une réponse
    apparaît dans le journal avec period/length/loop/end décodés -> OK/KO

  Test 6 (si Chemin B utilisé) — Push WAV
    Envoyer un WAV court vers un slot de test (pas S1 si tu as un son
    important dessus) -> "Receiving smpl" visible sur le X7000, puis
    lecture correcte via le bouton "PB" -> OK/KO

================================================================================
 FIN DE LA NOTICE
================================================================================
